@poetora/cli 0.0.1 → 0.1.2

package/src/errors/cli-error.ts

@@ -0,0 +1,83 @@
+/**
+ * Base CLI error class for all custom errors
+ */
+export class CliError extends Error {
+  constructor(
+    message: string,
+    public readonly code: string,
+    public readonly exitCode: number = 1
+  ) {
+    super(message);
+    this.name = 'CliError';
+    Error.captureStackTrace(this, this.constructor);
+  }
+}
+
+/**
+ * Error thrown when environment requirements are not met
+ */
+export class InvalidEnvironmentError extends CliError {
+  constructor(message: string) {
+    super(message, 'INVALID_ENVIRONMENT', 1);
+    this.name = 'InvalidEnvironmentError';
+  }
+}
+
+/**
+ * Error thrown when no available port is found
+ */
+export class NoAvailablePortError extends CliError {
+  constructor(message: string) {
+    super(message, 'NO_AVAILABLE_PORT', 1);
+    this.name = 'NoAvailablePortError';
+  }
+}
+
+/**
+ * Error thrown when configuration file is not found
+ */
+export class ConfigNotFoundError extends CliError {
+  constructor(message: string) {
+    super(message, 'CONFIG_NOT_FOUND', 1);
+    this.name = 'ConfigNotFoundError';
+  }
+}
+
+/**
+ * Error thrown when command validation fails
+ */
+export class ValidationError extends CliError {
+  constructor(
+    message: string,
+    public readonly field?: string
+  ) {
+    super(message, 'VALIDATION_ERROR', 1);
+    this.name = 'ValidationError';
+  }
+}
+
+/**
+ * Error thrown when file operations fail
+ */
+export class FileSystemError extends CliError {
+  constructor(
+    message: string,
+    public readonly filePath?: string
+  ) {
+    super(message, 'FILE_SYSTEM_ERROR', 1);
+    this.name = 'FileSystemError';
+  }
+}
+
+/**
+ * Error thrown when external service calls fail
+ */
+export class ExternalServiceError extends CliError {
+  constructor(
+    message: string,
+    public readonly service?: string
+  ) {
+    super(message, 'EXTERNAL_SERVICE_ERROR', 1);
+    this.name = 'ExternalServiceError';
+  }
+}

package/src/errors/index.ts

@@ -0,0 +1 @@
+export * from './cli-error.js';

package/src/index.ts

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
-import { spawn, type ChildProcess } from 'child_process';
-import path from 'path';
-import { fileURLToPath } from 'url';
+import { type ChildProcess, spawn } from 'node:child_process';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -31,12 +31,12 @@ const cleanup = async (): Promise<void> => {
           resolve();
         }, 5000);
 
-        cli!.once('exit', () => {
+        cli?.once('exit', () => {
           clearTimeout(timeout);
           resolve();
         });
       });
-    } catch (error) {
+    } catch (_error) {
       // ignore
     }
   }
@@ -101,7 +101,7 @@ process.on('exit', () => {
   if (cli && !cli.killed) {
     try {
       cli.kill('SIGKILL');
-    } catch (error) {
+    } catch (_error) {
       // ignore
     }
   }

package/src/mdxAccessibility.ts

@@ -1,10 +1,9 @@
+import fs from 'node:fs';
+import path from 'node:path';
 import { categorizeFilePaths, getPoetIgnore } from '@poetora/prebuild';
 import { coreRemark } from '@poetora/shared';
-import fs from 'fs';
-import type { Root, Text } from 'mdast';
-import type { Node } from 'mdast';
+import type { Node, Root, Text } from 'mdast';
 import type { MdxJsxFlowElement } from 'mdast-util-mdx-jsx';
-import path from 'path';
 import { visit } from 'unist-util-visit';
 
 export interface AccessibilityFixAttribute {

package/src/services/__tests__/port.service.test.ts

@@ -0,0 +1,83 @@
+import detect from 'detect-port';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { NoAvailablePortError } from '../../errors/index.js';
+import { CLI_CONSTANTS } from '../../types/index.js';
+import { PortService } from '../port.service.js';
+
+vi.mock('detect-port');
+
+describe('PortService', () => {
+  let service: PortService;
+  const mockDetect = vi.mocked(detect);
+
+  beforeEach(() => {
+    service = new PortService();
+    vi.clearAllMocks();
+  });
+
+  describe('findAvailablePort', () => {
+    it('should return preferred port when available', async () => {
+      mockDetect.mockResolvedValue(3000);
+
+      const port = await service.findAvailablePort(3000);
+
+      expect(port).toBe(3000);
+      expect(mockDetect).toHaveBeenCalledWith(3000);
+    });
+
+    it('should return default port when no preferred port specified', async () => {
+      mockDetect.mockResolvedValue(CLI_CONSTANTS.PORT.DEFAULT);
+
+      const port = await service.findAvailablePort();
+
+      expect(port).toBe(CLI_CONSTANTS.PORT.DEFAULT);
+    });
+
+    it('should try next port when first is occupied', async () => {
+      mockDetect.mockResolvedValueOnce(3001); // 3000 occupied
+      mockDetect.mockResolvedValueOnce(3001); // 3001 available
+
+      const port = await service.findAvailablePort(3000);
+
+      expect(port).toBe(3001);
+      expect(mockDetect).toHaveBeenCalledTimes(2);
+      expect(mockDetect).toHaveBeenNthCalledWith(1, 3000);
+      expect(mockDetect).toHaveBeenNthCalledWith(2, 3001);
+    });
+
+    it('should try multiple ports until finding available one', async () => {
+      // Ports 3000, 3001, 3002 are occupied
+      mockDetect.mockResolvedValueOnce(3001);
+      mockDetect.mockResolvedValueOnce(3002);
+      mockDetect.mockResolvedValueOnce(3003);
+      // Port 3003 is available
+      mockDetect.mockResolvedValueOnce(3003);
+
+      const port = await service.findAvailablePort(3000);
+
+      expect(port).toBe(3003);
+      expect(mockDetect).toHaveBeenCalledTimes(4);
+    });
+
+    it('should throw NoAvailablePortError after MAX_ATTEMPTS', async () => {
+      // All ports are occupied
+      mockDetect.mockImplementation((port) => Promise.resolve((port as number) + 1));
+
+      await expect(service.findAvailablePort(3000)).rejects.toThrow(NoAvailablePortError);
+      expect(mockDetect).toHaveBeenCalledTimes(CLI_CONSTANTS.PORT.MAX_ATTEMPTS);
+    });
+
+    it('should include start port in error message', async () => {
+      mockDetect.mockImplementation((port) => Promise.resolve((port as number) + 1));
+
+      try {
+        await service.findAvailablePort(5000);
+        expect.fail('Should have thrown error');
+      } catch (error) {
+        expect(error).toBeInstanceOf(NoAvailablePortError);
+        expect((error as NoAvailablePortError).message).toContain('5000');
+      }
+    });
+  });
+});

package/src/services/__tests__/template.service.test.ts

@@ -0,0 +1,234 @@
+import * as fs from 'node:fs';
+import AdmZip from 'adm-zip';
+import * as fse from 'fs-extra';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { ExternalServiceError, FileSystemError } from '../../errors/index.js';
+import { TemplateService } from '../template.service.js';
+
+vi.mock('node:fs', () => ({
+  default: {
+    promises: {
+      readdir: vi.fn(),
+      writeFile: vi.fn(),
+      readFile: vi.fn(),
+    },
+  },
+  promises: {
+    readdir: vi.fn(),
+    writeFile: vi.fn(),
+    readFile: vi.fn(),
+  },
+}));
+
+vi.mock('fs-extra');
+vi.mock('adm-zip', () => ({
+  default: vi.fn(),
+}));
+
+describe('TemplateService', () => {
+  let service: TemplateService;
+
+  beforeEach(() => {
+    service = new TemplateService();
+    vi.clearAllMocks();
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  describe('checkDirectory', () => {
+    it('should return exists=true and hasContents=true for non-empty directory', async () => {
+      vi.mocked(fse.ensureDir).mockResolvedValue(undefined);
+      vi.mocked(fs.promises.readdir).mockResolvedValue([
+        'file1.txt',
+        'file2.txt',
+      ] as unknown as fs.Dirent[]);
+
+      const result = await service.checkDirectory('/test/dir');
+
+      expect(result).toEqual({
+        exists: true,
+        hasContents: true,
+      });
+      expect(fse.ensureDir).toHaveBeenCalledWith('/test/dir');
+    });
+
+    it('should return exists=true and hasContents=false for empty directory', async () => {
+      vi.mocked(fse.ensureDir).mockResolvedValue(undefined);
+      vi.mocked(fs.promises.readdir).mockResolvedValue([] as unknown as fs.Dirent[]);
+
+      const result = await service.checkDirectory('/test/empty');
+
+      expect(result).toEqual({
+        exists: true,
+        hasContents: false,
+      });
+    });
+
+    it('should return exists=false for non-existent directory on ENOENT', async () => {
+      const error = new Error('ENOENT') as NodeJS.ErrnoException;
+      error.code = 'ENOENT';
+      vi.mocked(fse.ensureDir).mockRejectedValue(error);
+
+      const result = await service.checkDirectory('/nonexistent');
+
+      expect(result).toEqual({
+        exists: false,
+        hasContents: false,
+      });
+    });
+
+    it('should throw FileSystemError for other errors', async () => {
+      vi.mocked(fse.ensureDir).mockRejectedValue(new Error('Permission denied'));
+
+      await expect(service.checkDirectory('/test/dir')).rejects.toThrow(FileSystemError);
+    });
+  });
+
+  describe('getAvailableThemes', () => {
+    it('should return available themes from docsConfigSchema', () => {
+      const themes = service.getAvailableThemes();
+
+      expect(themes).toBeInstanceOf(Array);
+      expect(themes.length).toBeGreaterThan(0);
+      expect(themes).toContain('ora');
+    });
+  });
+
+  describe('installTemplate', () => {
+    const mockFetch = vi.fn();
+    const originalFetch = global.fetch;
+
+    beforeEach(() => {
+      global.fetch = mockFetch;
+
+      // Mock successful download
+      mockFetch.mockResolvedValue({
+        ok: true,
+        arrayBuffer: vi.fn().mockResolvedValue(new ArrayBuffer(8)),
+      });
+
+      // Mock file operations
+      vi.mocked(fs.promises.writeFile).mockResolvedValue(undefined);
+      vi.mocked(fs.promises.readFile).mockResolvedValue('{}');
+      vi.mocked(fse.ensureDir).mockResolvedValue(undefined);
+      vi.mocked(fse.copy).mockResolvedValue(undefined);
+      vi.mocked(fse.remove).mockResolvedValue(undefined);
+
+      // Mock AdmZip constructor - must use function for constructor
+      vi.mocked(AdmZip).mockImplementation(function (this: AdmZip) {
+        return {
+          extractAllTo: vi.fn(),
+        } as unknown as AdmZip;
+      } as unknown as typeof AdmZip);
+    });
+
+    afterEach(() => {
+      global.fetch = originalFetch;
+    });
+
+    it('should successfully install template', async () => {
+      await service.installTemplate({
+        directory: '/test/project',
+        projectName: 'My Project',
+        theme: 'quartz',
+      });
+
+      expect(mockFetch).toHaveBeenCalledWith(
+        'https://github.com/poetora/starter/archive/refs/heads/main.zip'
+      );
+      expect(fse.copy).toHaveBeenCalled();
+      expect(fs.promises.writeFile).toHaveBeenCalledWith(
+        '/test/project/docs.json',
+        expect.stringContaining('My Project'),
+        'utf-8'
+      );
+    });
+
+    it('should throw ExternalServiceError on download failure', async () => {
+      mockFetch.mockResolvedValue({
+        ok: false,
+        status: 404,
+        statusText: 'Not Found',
+      });
+
+      await expect(
+        service.installTemplate({
+          directory: '/test/project',
+          projectName: 'My Project',
+          theme: 'quartz',
+        })
+      ).rejects.toThrow(ExternalServiceError);
+    });
+
+    it('should cleanup temporary files after successful installation', async () => {
+      await service.installTemplate({
+        directory: '/test/project',
+        projectName: 'My Project',
+        theme: 'quartz',
+      });
+
+      expect(fse.remove).toHaveBeenCalledWith('poetora-starter.zip');
+      expect(fse.remove).toHaveBeenCalledWith('poetora-starter-temp');
+    });
+
+    it('should cleanup temporary files even on error', async () => {
+      vi.mocked(fse.copy).mockRejectedValue(new Error('Copy failed'));
+
+      await expect(
+        service.installTemplate({
+          directory: '/test/project',
+          projectName: 'My Project',
+          theme: 'quartz',
+        })
+      ).rejects.toThrow();
+
+      expect(fse.remove).toHaveBeenCalled();
+    });
+
+    it('should handle missing docs.json by creating new config', async () => {
+      vi.mocked(fs.promises.readFile).mockRejectedValue(new Error('ENOENT'));
+
+      await service.installTemplate({
+        directory: '/test/project',
+        projectName: 'My Project',
+        theme: 'quartz',
+      });
+
+      expect(fs.promises.writeFile).toHaveBeenCalledWith(
+        '/test/project/docs.json',
+        expect.stringContaining('"name": "My Project"'),
+        'utf-8'
+      );
+    });
+
+    it('should preserve existing config fields when updating', async () => {
+      vi.mocked(fs.promises.readFile).mockResolvedValue(
+        JSON.stringify({
+          name: 'Old Name',
+          theme: 'old-theme',
+          customField: 'preserved',
+        })
+      );
+
+      await service.installTemplate({
+        directory: '/test/project',
+        projectName: 'New Project',
+        theme: 'quartz',
+      });
+
+      const writeCall = vi
+        .mocked(fs.promises.writeFile)
+        .mock.calls.find((call) => call[0] === '/test/project/docs.json');
+
+      expect(writeCall).toBeDefined();
+      const writtenConfig = JSON.parse(writeCall?.[1] as string);
+      expect(writtenConfig).toMatchObject({
+        name: 'New Project',
+        theme: 'quartz',
+        customField: 'preserved',
+      });
+    });
+  });
+});

package/src/services/__tests__/version.service.test.ts

@@ -0,0 +1,165 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { VersionService } from '../version.service.js';
+
+describe('VersionService', () => {
+  let service: VersionService;
+  let _originalVersion: string;
+
+  beforeEach(() => {
+    service = new VersionService();
+    _originalVersion = process.version;
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  describe('parseNodeVersion', () => {
+    it('should parse version with v prefix', () => {
+      vi.spyOn(process, 'version', 'get').mockReturnValue('v20.17.0');
+
+      const version = service.parseNodeVersion();
+
+      expect(version.major).toBe(20);
+      expect(version.minor).toBe(17);
+      expect(version.patch).toBe(0);
+      expect(version.raw).toBe('20.17.0');
+    });
+
+    it('should parse version without v prefix', () => {
+      vi.spyOn(process, 'version', 'get').mockReturnValue('18.0.0');
+
+      const version = service.parseNodeVersion();
+
+      expect(version.major).toBe(18);
+      expect(version.minor).toBe(0);
+      expect(version.patch).toBe(0);
+    });
+
+    it('should parse version with only major.minor', () => {
+      vi.spyOn(process, 'version', 'get').mockReturnValue('v20.17');
+
+      const version = service.parseNodeVersion();
+
+      expect(version.major).toBe(20);
+      expect(version.minor).toBe(17);
+      expect(version.patch).toBe(0);
+    });
+  });
+
+  describe('checkNodeVersion', () => {
+    it('should pass for Node 20.17.0', () => {
+      vi.spyOn(process, 'version', 'get').mockReturnValue('v20.17.0');
+
+      const result = service.checkNodeVersion();
+
+      expect(result.isValid).toBe(true);
+      expect(result.hasWarning).toBe(false);
+    });
+
+    it('should pass for Node 18.0.0 (minimum)', () => {
+      vi.spyOn(process, 'version', 'get').mockReturnValue('v18.0.0');
+
+      const result = service.checkNodeVersion();
+
+      expect(result.isValid).toBe(true);
+      expect(result.hasWarning).toBe(true);
+      expect(result.message).toContain('20.17');
+    });
+
+    it('should pass for Node 24.x', () => {
+      vi.spyOn(process, 'version', 'get').mockReturnValue('v24.0.0');
+
+      const result = service.checkNodeVersion();
+
+      expect(result.isValid).toBe(true);
+    });
+
+    it('should fail for Node 17.x', () => {
+      vi.spyOn(process, 'version', 'get').mockReturnValue('v17.9.0');
+
+      const result = service.checkNodeVersion();
+
+      expect(result.isValid).toBe(false);
+      expect(result.message).toContain('18.0');
+    });
+
+    it('should fail for Node 25.x', () => {
+      vi.spyOn(process, 'version', 'get').mockReturnValue('v25.0.0');
+
+      const result = service.checkNodeVersion();
+
+      expect(result.isValid).toBe(false);
+      expect(result.message).toContain('not supported');
+    });
+
+    it('should warn for Node 19.x (below recommended)', () => {
+      vi.spyOn(process, 'version', 'get').mockReturnValue('v19.5.0');
+
+      const result = service.checkNodeVersion();
+
+      expect(result.isValid).toBe(true);
+      expect(result.hasWarning).toBe(true);
+      expect(result.message).toContain('recommended');
+    });
+
+    it('should warn for Node 20.16 (below recommended minor)', () => {
+      vi.spyOn(process, 'version', 'get').mockReturnValue('v20.16.0');
+
+      const result = service.checkNodeVersion();
+
+      expect(result.isValid).toBe(true);
+      expect(result.hasWarning).toBe(true);
+    });
+  });
+
+  describe('getCliVersion', () => {
+    it('should return test-cli in test mode', () => {
+      const originalEnv = process.env.CLI_TEST_MODE;
+      process.env.CLI_TEST_MODE = 'true';
+
+      const version = service.getCliVersion();
+
+      expect(version).toBe('test-cli');
+
+      process.env.CLI_TEST_MODE = originalEnv;
+    });
+
+    it('should return version from package.json', () => {
+      const version = service.getCliVersion();
+
+      expect(version).toBeDefined();
+      expect(typeof version).toBe('string');
+    });
+  });
+
+  describe('getLatestCliVersion', () => {
+    it('should return latest version from npm', () => {
+      const version = service.getLatestCliVersion('@poetora/cli');
+
+      expect(version).toBeDefined();
+      expect(typeof version).toBe('string');
+      expect(version).toMatch(/^\d+\.\d+\.\d+/);
+    });
+  });
+
+  describe('isVersionUpToDate', () => {
+    it('should return true when versions match', () => {
+      const result = service.isVersionUpToDate('1.0.0', '1.0.0');
+
+      expect(result).toBe(true);
+    });
+
+    it('should return false when versions differ', () => {
+      const result = service.isVersionUpToDate('1.0.0', '1.0.1');
+
+      expect(result).toBe(false);
+    });
+
+    it('should handle whitespace', () => {
+      const result = service.isVersionUpToDate('1.0.0  ', '  1.0.0');
+
+      expect(result).toBe(true);
+    });
+  });
+});