@poetora/cli 0.0.1 → 0.1.2

package/src/accessibility.ts

@@ -157,8 +157,8 @@ export function checkDocsColors(
     ...anchorResults.flatMap((anchor) => [anchor.lightContrast, anchor.darkContrast]),
   ].filter(Boolean);
 
-  const hasFailure = results.some((result) => result!.recommendation === 'fail');
-  const hasWarning = results.some((result) => result!.recommendation === 'warning');
+  const hasFailure = results.some((result) => result?.recommendation === 'fail');
+  const hasWarning = results.some((result) => result?.recommendation === 'warning');
 
   let overallScore: 'pass' | 'warning' | 'fail';
   if (hasFailure) {

package/src/cli-builder.ts

@@ -0,0 +1,267 @@
+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 {
+  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)
+        // 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();
+            this.logger.log(`cli version: ${versions.cli}`);
+            this.logger.log(`client version: ${versions.client}`);
+            process.exit(0);
+          }
+        )
+        // Error handling
+        .strictCommands()
+        .demandCommand(1, 'unknown command. see above for the list of supported commands.')
+        .alias('h', 'help')
+        .alias('v', 'version')
+    );
+  }
+
+  /**
+   * Parse and execute CLI
+   */
+  async run(): Promise<void> {
+    await this.build().parseAsync();
+  }
+}

package/src/cli.ts

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+import { CliBuilder } from './cli-builder.js';
+
+export interface CliOptions {
+  packageName: string;
+}
+
+export const cli = (options: CliOptions): void => {
+  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

@@ -0,0 +1,145 @@
+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');
+      const consoleErrorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+
+      await expect(command.run({ value: 'test' })).rejects.toBe('string error');
+
+      expect(mockLogger.error).toHaveBeenCalledWith('An unexpected error occurred');
+      expect(consoleErrorSpy).toHaveBeenCalledWith('string error');
+
+      consoleErrorSpy.mockRestore();
+    });
+
+    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);
+      const consoleErrorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+
+      await expect(command.run({ value: 'test' })).rejects.toThrow(error);
+
+      expect(consoleErrorSpy).toHaveBeenCalledWith(error.stack);
+
+      consoleErrorSpy.mockRestore();
+      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

@@ -0,0 +1,241 @@
+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');
+    });
+  });
+});