@poetora/cli 0.1.9 → 0.1.11

package/src/cli-builder.ts

@@ -1,274 +0,0 @@
-import chalk from 'chalk';
-import type { Argv } from 'yargs';
-import yargs from 'yargs';
-import { hideBin } from 'yargs/helpers';
-import {
-  CheckCommand,
-  DevCommand,
-  InitCommand,
-  LinkCommand,
-  UpdateCommand,
-} from './commands/index.js';
-import { checkNodeVersion, suppressConsoleWarnings } from './middlewares.js';
-import {
-  AccessibilityCheckService,
-  LinkService,
-  OpenApiCheckService,
-  PortService,
-  TemplateService,
-  UpdateService,
-  VersionService,
-} from './services/index.js';
-import type { DevOptions, OpenApiCheckOptions, RenameOptions } from './types/index.js';
-import type { ILogger } from './utils/index.js';
-import { ConsoleLogger } from './utils/index.js';
-
-/**
- * CLI Builder - Orchestrates all commands using yargs
- */
-export class CliBuilder {
-  private logger: ILogger;
-
-  constructor(private readonly packageName: string = 'poet') {
-    this.logger = new ConsoleLogger();
-  }
-
-  /**
-   * Build and configure the CLI
-   */
-  build(): Argv {
-    // Create services
-    const versionService = new VersionService(this.packageName);
-    const portService = new PortService(this.logger);
-    const templateService = new TemplateService();
-    const openApiCheckService = new OpenApiCheckService(this.logger);
-    const accessibilityCheckService = new AccessibilityCheckService();
-    const linkService = new LinkService(this.logger);
-    const updateService = new UpdateService(this.logger, versionService, this.packageName);
-
-    // Create commands
-    const devCommand = new DevCommand(this.logger, versionService, portService, this.packageName);
-    const initCommand = new InitCommand(this.logger, templateService, this.packageName);
-    const checkCommand = new CheckCommand(
-      this.logger,
-      openApiCheckService,
-      accessibilityCheckService,
-      this.packageName
-    );
-    const linkCommand = new LinkCommand(this.logger, linkService, this.packageName);
-    const updateCommand = new UpdateCommand(this.logger, updateService, this.packageName);
-
-    return (
-      yargs(hideBin(process.argv))
-        .scriptName(this.packageName)
-        .version()
-        .middleware(checkNodeVersion) // Check Node.js version before any command
-        .middleware(suppressConsoleWarnings) // Suppress known console warnings
-        // Dev command
-        .command(
-          'dev',
-          'initialize a local preview environment',
-          (yargs) =>
-            yargs
-              .option('port', {
-                type: 'number',
-                description: 'port to run the preview server on',
-                default: 3000,
-              })
-              .option('open', {
-                type: 'boolean',
-                default: true,
-                description: 'open a local preview in the browser',
-              })
-              .option('local-schema', {
-                type: 'boolean',
-                default: false,
-                hidden: true,
-                description:
-                  'use a locally hosted schema file (note: only https protocol is supported in production)',
-              })
-              .option('client-version', {
-                type: 'string',
-                hidden: true,
-                description: 'the version of the client to use for cli testing',
-              })
-              .option('groups', {
-                type: 'array',
-                description: 'Mock user groups for local development and testing',
-                example: '--groups admin user',
-              })
-              .option('disable-openapi', {
-                type: 'boolean',
-                default: false,
-                description: 'Disable OpenAPI file generation',
-              }),
-          async (argv) => {
-            try {
-              await devCommand.run(argv as DevOptions);
-            } catch (error) {
-              this.logger.error(error instanceof Error ? error.message : 'Unknown error');
-              process.exit(1);
-            }
-          }
-        )
-        // Init/New command
-        .command(
-          ['new [directory]', 'init [directory]'],
-          'Create a new Poetora documentation site',
-          (yargs) =>
-            yargs.positional('directory', {
-              describe: 'The directory to initialize your documentation',
-              type: 'string',
-              default: '.',
-            }),
-          async (argv) => {
-            try {
-              await initCommand.run({ directory: argv.directory as string });
-            } catch (error) {
-              this.logger.error(error instanceof Error ? error.message : 'Unknown error');
-              process.exit(1);
-            }
-          }
-        )
-        // OpenAPI check command
-        .command(
-          'openapi-check <filename>',
-          'check if an OpenAPI spec is valid',
-          (yargs) =>
-            yargs
-              .positional('filename', {
-                describe:
-                  'the filename of the OpenAPI spec (e.g. ./openapi.yaml) or the URL to the OpenAPI spec',
-                type: 'string',
-                demandOption: true,
-              })
-              .option('local-schema', {
-                type: 'boolean',
-                default: false,
-                description:
-                  'use a locally hosted schema file (note: only https protocol is supported in production)',
-              }),
-          async (argv) => {
-            try {
-              await checkCommand.checkOpenApi({
-                filename: argv.filename as string,
-                localSchema: argv.localSchema,
-              } as OpenApiCheckOptions);
-              process.exit(0);
-            } catch (error) {
-              this.logger.error(error instanceof Error ? error.message : 'Unknown error');
-              process.exit(1);
-            }
-          }
-        )
-        // Accessibility check command
-        .command(
-          ['a11y', 'accessibility-check', 'a11y-check', 'accessibility'],
-          'check for accessibility issues in documentation',
-          () => undefined,
-          async () => {
-            try {
-              const exitCode = await checkCommand.checkAccessibility();
-              process.exit(exitCode);
-            } catch (error) {
-              this.logger.error(error instanceof Error ? error.message : 'Unknown error');
-              process.exit(1);
-            }
-          }
-        )
-        // Broken links command
-        .command(
-          'broken-links',
-          'check for invalid internal links',
-          () => undefined,
-          async () => {
-            try {
-              const brokenLinks = await linkCommand.checkBrokenLinks();
-              const hasBrokenLinks = Object.keys(brokenLinks).length > 0;
-              process.exit(hasBrokenLinks ? 1 : 0);
-            } catch (error) {
-              this.logger.error(error instanceof Error ? error.message : 'Unknown error');
-              process.exit(1);
-            }
-          }
-        )
-        // Rename command
-        .command(
-          'rename <from> <to>',
-          'rename a file and update all internal link references',
-          (yargs) =>
-            yargs
-              .positional('from', {
-                describe: 'the file to rename',
-                type: 'string',
-              })
-              .positional('to', {
-                describe: 'the new name for the file',
-                type: 'string',
-              })
-              .demandOption(['from', 'to'])
-              .option('force', {
-                type: 'boolean',
-                default: false,
-                description: 'rename files and skip errors',
-              })
-              .epilog(`example: \`${this.packageName} rename introduction.mdx overview.mdx\``),
-          async (argv) => {
-            try {
-              await linkCommand.renameFile({
-                from: argv.from as string,
-                to: argv.to as string,
-                force: argv.force,
-              } as RenameOptions);
-              process.exit(0);
-            } catch (error) {
-              this.logger.error(error instanceof Error ? error.message : 'Unknown error');
-              process.exit(1);
-            }
-          }
-        )
-        // Update command
-        .command(
-          'update',
-          'update the CLI to the latest version',
-          () => undefined,
-          async () => {
-            try {
-              await updateCommand.run({});
-              process.exit(0);
-            } catch (error) {
-              this.logger.error(error instanceof Error ? error.message : 'Unknown error');
-              process.exit(1);
-            }
-          }
-        )
-        // Version command
-        .command(
-          ['version', 'v'],
-          'display the current version of the CLI and client',
-          () => undefined,
-          async () => {
-            const versions = versionService.getVersions();
-            // Use chalk for consistent formatting
-            console.log(`${chalk.bold.green('cli version')} ${versions.cli}`);
-            console.log(`${chalk.bold.green('client version')} ${versions.client}`);
-            process.exit(0);
-          }
-        )
-        // Error handling
-        .strictCommands()
-        .demandCommand(1, 'unknown command. see above for the list of supported commands.')
-
-        // Alias option flags --help = -h, default --version = -v
-        .alias('h', 'help')
-        .alias('v', 'version')
-    );
-  }
-
-  /**
-   * Parse and execute CLI
-   */
-  async run(): Promise<void> {
-    await this.build().parseAsync();
-  }
-}

package/src/cli.ts

@@ -1,22 +0,0 @@
-#!/usr/bin/env node
-import { Logs } from '@poetora/previewing';
-import { render } from 'ink';
-import React from 'react';
-
-import { CliBuilder } from './cli-builder.js';
-
-export interface CliOptions {
-  packageName: string;
-}
-
-export const cli = (options: CliOptions): void => {
-  // Initialize ink rendering for logs
-  render(React.createElement(Logs));
-
-  const builder = new CliBuilder(options.packageName);
-
-  builder.run().catch((error) => {
-    console.error('Fatal error:', error);
-    process.exit(1);
-  });
-};

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

@@ -1,139 +0,0 @@
-import { beforeEach, describe, expect, it, vi } from 'vitest';
-import { CliError, ValidationError } from '../../errors/index.js';
-import type { ILogger } from '../../utils/index.js';
-import { BaseCommand } from '../base.command.js';
-
-// Test command implementation
-class TestCommand extends BaseCommand {
-  readonly name = 'test';
-  readonly description = 'Test command';
-
-  public validateCalled = false;
-  public executeCalled = false;
-
-  protected override async validate(options: { value: string }): Promise<void> {
-    this.validateCalled = true;
-    if (!options.value) {
-      throw new ValidationError('value is required');
-    }
-  }
-
-  protected override async execute(options: { value: string }): Promise<string> {
-    this.executeCalled = true;
-    return `executed with ${options.value}`;
-  }
-}
-
-describe('BaseCommand', () => {
-  let mockLogger: ILogger;
-  let command: TestCommand;
-
-  beforeEach(() => {
-    mockLogger = {
-      info: vi.fn(),
-      success: vi.fn(),
-      error: vi.fn(),
-      warn: vi.fn(),
-      log: vi.fn(),
-      spinner: vi.fn(),
-      logColor: vi.fn(),
-      logBold: vi.fn(),
-      logSeparator: vi.fn(),
-      logNewLine: vi.fn(),
-      logHeader: vi.fn(),
-    };
-    command = new TestCommand(mockLogger);
-  });
-
-  describe('run', () => {
-    it('should execute command successfully', async () => {
-      const result = await command.run({ value: 'test' });
-
-      expect(command.validateCalled).toBe(true);
-      expect(command.executeCalled).toBe(true);
-      expect(result).toBe('executed with test');
-    });
-
-    it('should validate before execute', async () => {
-      const callOrder: string[] = [];
-
-      // Use type assertion to bypass protected access for testing
-      (command as unknown as { validate: typeof command.validate }).validate = vi.fn(async () => {
-        callOrder.push('validate');
-      });
-      (command as unknown as { execute: typeof command.execute }).execute = vi.fn(async () => {
-        callOrder.push('execute');
-        return 'result';
-      });
-
-      await command.run({ value: 'test' });
-
-      expect(callOrder).toEqual(['validate', 'execute']);
-    });
-
-    it('should handle validation errors', async () => {
-      await expect(command.run({ value: '' })).rejects.toThrow(ValidationError);
-
-      expect(command.validateCalled).toBe(true);
-      expect(command.executeCalled).toBe(false);
-      expect(mockLogger.error).toHaveBeenCalledWith('value is required');
-    });
-
-    it('should handle execution errors', async () => {
-      (command as unknown as { execute: typeof command.execute }).execute = vi
-        .fn()
-        .mockRejectedValue(new Error('execution failed'));
-
-      await expect(command.run({ value: 'test' })).rejects.toThrow('execution failed');
-
-      expect(mockLogger.error).toHaveBeenCalledWith('execution failed');
-    });
-
-    it('should handle CliError specially', async () => {
-      const cliError = new CliError('CLI error message', 'TEST_ERROR', 1);
-      (command as unknown as { execute: typeof command.execute }).execute = vi
-        .fn()
-        .mockRejectedValue(cliError);
-
-      await expect(command.run({ value: 'test' })).rejects.toThrow(cliError);
-
-      expect(mockLogger.error).toHaveBeenCalledWith('CLI error message');
-    });
-
-    it('should handle unknown errors', async () => {
-      (command as unknown as { execute: typeof command.execute }).execute = vi
-        .fn()
-        .mockRejectedValue('string error');
-
-      await expect(command.run({ value: 'test' })).rejects.toBe('string error');
-
-      expect(mockLogger.error).toHaveBeenCalledWith('An unexpected error occurred');
-      expect(mockLogger.logColor).toHaveBeenCalledWith('string error', 'gray');
-    });
-
-    it('should show stack trace in debug mode', async () => {
-      const originalDebug = process.env.DEBUG;
-      process.env.DEBUG = 'true';
-
-      const error = new Error('test error');
-      (command as unknown as { execute: typeof command.execute }).execute = vi
-        .fn()
-        .mockRejectedValue(error);
-
-      await expect(command.run({ value: 'test' })).rejects.toThrow(error);
-
-      expect(mockLogger.logColor).toHaveBeenCalledWith(error.stack ?? '', 'gray');
-      process.env.DEBUG = originalDebug;
-    });
-  });
-
-  describe('command metadata', () => {
-    it('should have name property', () => {
-      expect(command.name).toBe('test');
-    });
-
-    it('should have description property', () => {
-      expect(command.description).toBe('Test command');
-    });
-  });
-});

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

@@ -1,241 +0,0 @@
-import * as previewing from '@poetora/previewing';
-import { beforeEach, describe, expect, it, vi } from 'vitest';
-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 { DevCommand } from '../dev.command.js';
-
-vi.mock('@poetora/previewing', async () => {
-  const actual = await vi.importActual<typeof import('@poetora/previewing')>('@poetora/previewing');
-  return {
-    ...actual,
-    dev: vi.fn(),
-  };
-});
-
-describe('DevCommand', () => {
-  let mockLogger: ILogger;
-  let mockVersionService: VersionService;
-  let mockPortService: PortService;
-  let command: DevCommand;
-  const devSpy = vi.mocked(previewing.dev);
-
-  beforeEach(() => {
-    mockLogger = {
-      info: vi.fn(),
-      success: vi.fn(),
-      error: vi.fn(),
-      warn: vi.fn(),
-      log: vi.fn(),
-      spinner: vi.fn(),
-      logColor: vi.fn(),
-      logBold: vi.fn(),
-      logSeparator: vi.fn(),
-      logNewLine: vi.fn(),
-      logHeader: vi.fn(),
-    };
-
-    mockVersionService = {
-      checkNodeVersion: vi.fn(),
-      getCliVersion: vi.fn(),
-      parseNodeVersion: vi.fn(),
-      getClientVersion: vi.fn(),
-      getVersions: vi.fn(),
-      getLatestCliVersion: vi.fn(),
-      isVersionUpToDate: vi.fn(),
-      validateNodeVersion: vi.fn(),
-    } as unknown as VersionService;
-
-    mockPortService = {
-      findAvailablePort: vi.fn(),
-    } as unknown as PortService;
-
-    command = new DevCommand(mockLogger, mockVersionService, mockPortService, 'poet');
-
-    vi.clearAllMocks();
-  });
-
-  describe('validate', () => {
-    it('should pass validation for supported Node version', async () => {
-      vi.mocked(mockVersionService.checkNodeVersion).mockReturnValue({
-        isValid: true,
-        hasWarning: false,
-      });
-
-      await expect(command.validate({} as DevOptions)).resolves.not.toThrow();
-
-      expect(mockVersionService.checkNodeVersion).toHaveBeenCalled();
-    });
-
-    it('should show warning for below recommended version', async () => {
-      vi.mocked(mockVersionService.checkNodeVersion).mockReturnValue({
-        isValid: true,
-        hasWarning: true,
-        message: 'Node.js 20.17.0 recommended',
-      });
-
-      await command.validate({} as DevOptions);
-
-      expect(mockLogger.warn).toHaveBeenCalledWith('Node.js 20.17.0 recommended');
-    });
-
-    it('should throw error for unsupported Node version', async () => {
-      vi.mocked(mockVersionService.checkNodeVersion).mockReturnValue({
-        isValid: false,
-        hasWarning: false,
-        message: 'Node.js 18.0.0 or higher required',
-      });
-
-      await expect(command.validate({} as DevOptions)).rejects.toThrow(InvalidEnvironmentError);
-    });
-  });
-
-  describe('execute', () => {
-    it('should start dev server with default options', async () => {
-      vi.mocked(mockPortService.findAvailablePort).mockResolvedValue(3000);
-      vi.mocked(mockVersionService.getCliVersion).mockReturnValue('1.0.0');
-      devSpy.mockResolvedValue(undefined);
-
-      const options: DevOptions = {};
-
-      await command.execute(options);
-
-      expect(mockPortService.findAvailablePort).toHaveBeenCalledWith(undefined);
-      expect(mockVersionService.getCliVersion).toHaveBeenCalled();
-      expect(devSpy).toHaveBeenCalledWith({
-        _: [],
-        $0: 'poet',
-        port: 3000,
-        open: true,
-        localSchema: false,
-        clientVersion: undefined,
-        groups: undefined,
-        disableOpenapi: false,
-        packageName: 'poet',
-        cliVersion: '1.0.0',
-      });
-    });
-
-    it('should use specified port', async () => {
-      vi.mocked(mockPortService.findAvailablePort).mockResolvedValue(5000);
-      vi.mocked(mockVersionService.getCliVersion).mockReturnValue('1.0.0');
-      devSpy.mockResolvedValue(undefined);
-
-      const options: DevOptions = { port: 5000 };
-
-      await command.execute(options);
-
-      expect(mockPortService.findAvailablePort).toHaveBeenCalledWith(5000);
-      expect(devSpy).toHaveBeenCalledWith(
-        expect.objectContaining({
-          port: 5000,
-        })
-      );
-    });
-
-    it('should respect open option', async () => {
-      vi.mocked(mockPortService.findAvailablePort).mockResolvedValue(3000);
-      vi.mocked(mockVersionService.getCliVersion).mockReturnValue('1.0.0');
-      devSpy.mockResolvedValue(undefined);
-
-      const options: DevOptions = { open: false };
-
-      await command.execute(options);
-
-      expect(devSpy).toHaveBeenCalledWith(
-        expect.objectContaining({
-          open: false,
-        })
-      );
-    });
-
-    it('should pass all options correctly', async () => {
-      vi.mocked(mockPortService.findAvailablePort).mockResolvedValue(4000);
-      vi.mocked(mockVersionService.getCliVersion).mockReturnValue('2.0.0');
-      devSpy.mockResolvedValue(undefined);
-
-      const options: DevOptions = {
-        port: 4000,
-        open: false,
-        localSchema: true,
-        clientVersion: '1.5.0',
-        groups: ['admin', 'user'],
-        disableOpenapi: true,
-      };
-
-      await command.execute(options);
-
-      expect(devSpy).toHaveBeenCalledWith({
-        _: [],
-        $0: 'poet',
-        port: 4000,
-        open: false,
-        localSchema: true,
-        clientVersion: '1.5.0',
-        groups: ['admin', 'user'],
-        disableOpenapi: true,
-        packageName: 'poet',
-        cliVersion: '2.0.0',
-      });
-    });
-
-    it('should handle when port service finds alternative port', async () => {
-      vi.mocked(mockPortService.findAvailablePort).mockResolvedValue(3001);
-      vi.mocked(mockVersionService.getCliVersion).mockReturnValue('1.0.0');
-      devSpy.mockResolvedValue(undefined);
-
-      const options: DevOptions = { port: 3000 };
-
-      await command.execute(options);
-
-      expect(devSpy).toHaveBeenCalledWith(
-        expect.objectContaining({
-          port: 3001, // Alternative port found
-        })
-      );
-    });
-  });
-
-  describe('run (integration)', () => {
-    it('should execute full flow successfully', async () => {
-      vi.mocked(mockVersionService.checkNodeVersion).mockReturnValue({
-        isValid: true,
-        hasWarning: false,
-      });
-      vi.mocked(mockPortService.findAvailablePort).mockResolvedValue(3000);
-      vi.mocked(mockVersionService.getCliVersion).mockReturnValue('1.0.0');
-      devSpy.mockResolvedValue(undefined);
-
-      await command.run({ port: 3000 });
-
-      expect(mockVersionService.checkNodeVersion).toHaveBeenCalled();
-      expect(mockPortService.findAvailablePort).toHaveBeenCalled();
-      expect(devSpy).toHaveBeenCalled();
-    });
-
-    it('should fail at validation stage for unsupported Node version', async () => {
-      vi.mocked(mockVersionService.checkNodeVersion).mockReturnValue({
-        isValid: false,
-        hasWarning: false,
-        message: 'Unsupported Node.js version',
-      });
-
-      await expect(command.run({})).rejects.toThrow(InvalidEnvironmentError);
-
-      // Should not reach execute stage
-      expect(mockPortService.findAvailablePort).not.toHaveBeenCalled();
-      expect(devSpy).not.toHaveBeenCalled();
-    });
-  });
-
-  describe('metadata', () => {
-    it('should have correct name', () => {
-      expect(command.name).toBe('dev');
-    });
-
-    it('should have correct description', () => {
-      expect(command.description).toBe('initialize a local preview environment');
-    });
-  });
-});