@hubspot/cms-component-library 0.1.0-alpha.1

package/README.md

@@ -0,0 +1,3 @@
+# HubSpot CMS React Component Library
+
+This is a WIP and is actively under construction. Breaking changes are expected.

package/cli/commands/customize.ts

@@ -0,0 +1,145 @@
+import { Command } from 'commander';
+import { multiselectPrompt, promptForNamingPrefix } from '../utils/prompts.js';
+import { logError, logSuccess } from '../utils/logging.js';
+import {
+  getAvailableComponents,
+  validateComponentExists,
+  findComponentName,
+} from '../utils/components.js';
+import { copyMultipleScaffolds } from '../utils/file-operations.js';
+import { validateAndFixPrefix } from '../utils/component-naming.js';
+
+const promptForPrefixAndFix = async (components: string[]): Promise<string> => {
+  const customName = await promptForNamingPrefix('', components.length);
+  return validateAndFixPrefix(customName);
+};
+
+const handleComponentCreationResults = (
+  results: {
+    successful: string[];
+    skipped: string[];
+    errors: { component: string; error: string }[];
+  },
+  componentPrefix: string
+) => {
+  if (results.successful.length > 0) {
+    logSuccess('✅ Successfully created customized components:');
+    results.successful.forEach((component: string) => {
+      logSuccess(`   📁 /components/hscl/${componentPrefix}${component}/`);
+    });
+  }
+
+  if (results.skipped.length > 0) {
+    console.log('\n⚠️  Skipped components:');
+    results.skipped.forEach((component: string) => {
+      console.log(
+        `   📁 /components/hscl/${componentPrefix}${component}/ (already exists)`
+      );
+    });
+  }
+
+  if (results.errors.length > 0) {
+    logError('\n❌ Errors occurred:');
+    results.errors.forEach(({ component, error }) => {
+      logError(`   ${componentPrefix}${component}: ${error}`);
+    });
+  }
+};
+
+const tryScaffoldComponents = async (
+  selectedComponents: string[],
+  componentPrefix: string
+) => {
+  try {
+    const results = await copyMultipleScaffolds({
+      sourceComponents: selectedComponents,
+      prefix: componentPrefix,
+    });
+
+    handleComponentCreationResults(results, componentPrefix);
+  } catch (error: unknown) {
+    logError(
+      `❌ Unexpected error: ${
+        error instanceof Error ? error.message : String(error)
+      }`
+    );
+  }
+};
+
+export function addCustomizeCommand(program: Command): void {
+  program
+    .command('customize [components...]')
+    .description(
+      'Scaffolds a new customized component. Takes in any number of components to customize. Use --list to see all available components.'
+    )
+    .option('--list', 'List all available components')
+    .action(async (components: string[], options: { list?: boolean }) => {
+      const availableComponents = await getAvailableComponents();
+      const hasComponents = components.length > 0;
+
+      // Scenario: user passed in --list flag or ran with no arguments (`npx hscl customize`) - jump into full interactive mode
+      if (options.list || !hasComponents) {
+        const { value: selectedComponents } = await multiselectPrompt({
+          message: 'Which component(s) do you want to generate?',
+          choices: availableComponents,
+        });
+
+        // if no components selected, exit
+        if (!selectedComponents || selectedComponents.length === 0) {
+          return;
+        }
+
+        // prefix prompt
+        const componentPrefix = await promptForPrefixAndFix(selectedComponents);
+
+        // scaffold components
+        await tryScaffoldComponents(selectedComponents, componentPrefix);
+
+        return;
+      }
+
+      // Scenario: source component(s) provided
+      if (hasComponents) {
+        let unknownComponentsCounter = 0;
+        const normalizedComponents: string[] = [];
+
+        for (const component of components) {
+          const componentExists = await validateComponentExists(component);
+
+          if (!componentExists) {
+            unknownComponentsCounter++;
+            continue;
+          }
+
+          // Get the correctly cased component name
+          const correctlyNamed = await findComponentName(
+            availableComponents,
+            component
+          );
+          if (correctlyNamed) {
+            normalizedComponents.push(correctlyNamed);
+          }
+        }
+
+        if (unknownComponentsCounter > 0) {
+          // validateComponentExists() above logs specific components not found (plus suggestions)
+          logError(
+            `❌ Please fix the invalid component name${
+              unknownComponentsCounter > 1 ? 's' : ''
+            }, and try again.\n`
+          );
+          return;
+        }
+
+        // prefix prompt
+        const componentPrefix = await promptForPrefixAndFix(
+          normalizedComponents
+        );
+
+        // scaffold components
+        await tryScaffoldComponents(normalizedComponents, componentPrefix);
+
+        return;
+      }
+    });
+}

package/cli/commands/help.ts

@@ -0,0 +1,56 @@
+import { Command } from 'commander';
+import { getVersion } from '../utils/version.js';
+import { CLI_metadata } from '../utils/cli-metadata.js';
+
+const showDescriptionAndVersionText = `${CLI_metadata.description}
+Version: v${getVersion()}`;
+
+const showAvailableCommands = `⚡️ AVAILABLE COMMANDS
+   | version     # Show version information
+   | help        # Display detailed help information (including examples)
+   | customize   # Scaffolds a new customized component`;
+
+const showCommandExamples = `✍️  EXAMPLES
+   | customize                 # Starts interactive mode
+   | customize --list          # Starts interactive mode (same as passing in no arguments)
+   | customize Button Heading  # Outputs Button and Heading components with customization`;
+
+export function addHelpCommand(program: Command): void {
+  program
+    .command('help')
+    .description('Display help information')
+    .action(() => {
+      console.log(`${showDescriptionAndVersionText}
+
+💭 PURPOSE
+   | A CLI tool for getting started quickly with the HubSpot
+   | CMS Component Library. With this tool, you can create
+   | new components, customize them, and build React modules
+   | using your new components.
+   |
+   | 💡 TIP: Run commands without arguments for interactive mode!
+
+${showAvailableCommands}
+
+${showCommandExamples}
+
+📚 MORE RESOURCES
+   > HubSpot CMS React documentation:
+     https://developers.hubspot.com/docs/guides/cms/react/modules
+  `);
+    });
+}
+
+export const outputQuickHelp = (unknownCommand: string | null): string => {
+  return `${
+    unknownCommand
+      ? `⛔ ${unknownCommand} is an invalid command`
+      : '⚠️  An argument is missing from your command'
+  }, but fret not!
+ℹ️  Here are some helpful commands and information to get you back on track:
+
+${showDescriptionAndVersionText}
+
+${showAvailableCommands}
+`;
+};

package/cli/commands/version.ts

@@ -0,0 +1,12 @@
+import { Command } from 'commander';
+import { getVersion } from '../utils/version.js';
+import { CLI_metadata } from '../utils/cli-metadata.js';
+
+export const addVersionCommand = (program: Command): void => {
+  program
+    .command('version')
+    .description('Show version number')
+    .action(() => {
+      console.log(`${CLI_metadata.description} v${getVersion()}`);
+    });
+};

package/cli/index.ts

@@ -0,0 +1,42 @@
+#!/usr/bin/env npx tsx
+
+import { Command } from 'commander';
+import { getVersion } from './utils/version.js';
+import { CLI_metadata } from './utils/cli-metadata.js';
+import { addVersionCommand } from './commands/version.js';
+import { addHelpCommand, outputQuickHelp } from './commands/help.js';
+import { addCustomizeCommand } from './commands/customize.js';
+
+const program: Command = new Command();
+
+program
+  .name(CLI_metadata.name)
+  .description(CLI_metadata.description)
+  .version(getVersion());
+
+addVersionCommand(program);
+
+addHelpCommand(program);
+
+addCustomizeCommand(program);
+
+// Catch no arguments or invalid commands --> show quick help and exit so terminal is ready to receive new commands
+
+// No arguments, exit normally
+// (i.e. argv only contains node path and script path, e.g. "npx hscl")
+if (process.argv.length === 2) {
+  const quickHelpText = outputQuickHelp(null);
+  console.log(quickHelpText);
+  process.exit(0); // exit code 0: success/normal termination, prevents Commander from adding more help text under our own
+}
+
+// Invalid commands, exit with error
+// (wildcard catches all unknown commands)
+// (e.g. "npx hscl fake_command")
+program.on('command:*', unknownCommand => {
+  const quickHelpText = outputQuickHelp(unknownCommand);
+  console.log(quickHelpText);
+  program.error(''); // exit with error formatting and empty error message (being handled above with console.log of quickHelpText)
+});
+
+program.parse();

package/cli/tests/commands.test.ts

@@ -0,0 +1,128 @@
+import {
+  describe,
+  it,
+  expect,
+  vi,
+  beforeEach,
+  afterEach,
+  type MockedFunction,
+} from 'vitest';
+import { readFileSync } from 'fs';
+import { CLI_metadata } from '../utils/cli-metadata.js';
+import type { Command } from 'commander';
+
+// Mock fs for getVersion dependency
+vi.mock('fs', () => ({
+  readFileSync: vi.fn(),
+}));
+
+describe('CLI Commands', () => {
+  let consoleSpy: MockedFunction<typeof console.log>;
+  let mockProgram: Pick<Command, 'command' | 'description' | 'action'> & {
+    command: MockedFunction<Command['command']>;
+    description: MockedFunction<Command['description']>;
+    action: MockedFunction<Command['action']>;
+  };
+
+  beforeEach(() => {
+    // Mock console.log to capture output
+    consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+
+    // Mock Commander program
+    mockProgram = {
+      command: vi.fn().mockReturnThis(),
+      description: vi.fn().mockReturnThis(),
+      action: vi.fn().mockReturnThis(),
+    };
+
+    // Setup mock package.json for getVersion
+    const mockPackageJson = JSON.stringify({
+      name: 'test-cli',
+      version: '1.0.0',
+    });
+    (readFileSync as MockedFunction<typeof readFileSync>).mockReturnValue(
+      mockPackageJson
+    );
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+    consoleSpy.mockRestore();
+  });
+
+  describe('version command', () => {
+    it('should register version command correctly', async () => {
+      const { addVersionCommand } = await import('../commands/version.ts');
+
+      addVersionCommand(mockProgram);
+
+      expect(mockProgram.command).toHaveBeenCalledWith('version');
+      expect(mockProgram.description).toHaveBeenCalledWith(
+        'Show version number'
+      );
+      expect(mockProgram.action).toHaveBeenCalledWith(expect.any(Function));
+    });
+
+    it('should output correct version information when executed', async () => {
+      const { addVersionCommand } = await import('../commands/version.ts');
+
+      addVersionCommand(mockProgram);
+
+      // Get the action function and execute it
+      const actionFunction = mockProgram.action.mock.calls[0][0];
+      actionFunction();
+
+      expect(consoleSpy).toHaveBeenCalledWith(
+        expect.stringContaining(`${CLI_metadata.description} v`)
+      );
+    });
+  });
+
+  describe('help command', () => {
+    it('should register help command correctly', async () => {
+      const { addHelpCommand } = await import('../commands/help.ts');
+
+      addHelpCommand(mockProgram);
+
+      expect(mockProgram.command).toHaveBeenCalledWith('help');
+      expect(mockProgram.description).toHaveBeenCalledWith(
+        'Display help information'
+      );
+      expect(mockProgram.action).toHaveBeenCalledWith(expect.any(Function));
+    });
+
+    it('should output comprehensive help information when executed', async () => {
+      const { addHelpCommand } = await import('../commands/help.ts');
+
+      addHelpCommand(mockProgram);
+
+      // Get the action function and execute it
+      const actionFunction = mockProgram.action.mock.calls[0][0];
+      actionFunction();
+
+      const output = consoleSpy.mock.calls[0][0];
+
+      // Verify key sections are present
+      expect(output).toContain(CLI_metadata.description);
+      expect(output).toContain('PURPOSE');
+      expect(output).toContain('COMMANDS');
+      expect(output).toContain('RESOURCES');
+    });
+  });
+
+  describe('help utility functions', () => {
+    it('should generate quick help output', async () => {
+      const { outputQuickHelp } = await import('../commands/help.ts');
+
+      const unknownCommandOutput = outputQuickHelp('invalidcmd');
+      const missingArgsOutput = outputQuickHelp();
+
+      expect(unknownCommandOutput).toContain(
+        'invalidcmd is an invalid command'
+      );
+      expect(missingArgsOutput).toContain('argument is missing');
+      expect(unknownCommandOutput).toContain(CLI_metadata.description);
+      expect(missingArgsOutput).toContain(CLI_metadata.description);
+    });
+  });
+});

package/cli/tests/get-file.test.ts

@@ -0,0 +1,82 @@
+import { describe, it, expect, vi, type MockedFunction } from 'vitest';
+import { readFileSync } from 'fs';
+import { getFileContents } from '../utils/file-operations.js';
+
+// Mock fs
+vi.mock('fs', () => ({
+  readFileSync: vi.fn(),
+}));
+
+describe('getFileContents', () => {
+  it('should read file contents successfully', () => {
+    const mockContent = 'file content';
+    (readFileSync as MockedFunction<typeof readFileSync>).mockReturnValue(
+      mockContent
+    );
+
+    // file name doesn't matter because we're mocking the readFileSync function above
+    const result = getFileContents('fakeFile.txt');
+
+    expect(result).toBe(mockContent);
+    expect(readFileSync).toHaveBeenCalledWith(
+      expect.stringContaining('fakeFile.txt'),
+      'utf8'
+    );
+  });
+
+  // error cases
+
+  it('should throw error with descriptive message for missing file', () => {
+    const error = new Error('File not found') as NodeJS.ErrnoException;
+    error.code = 'ENOENT';
+    (readFileSync as MockedFunction<typeof readFileSync>).mockImplementation(
+      () => {
+        throw error;
+      }
+    );
+
+    expect(() => getFileContents('missing.txt')).toThrow(/File not found/);
+  });
+
+  it('should throw error with descriptive message for permission denied', () => {
+    const error = new Error('Permission denied') as NodeJS.ErrnoException;
+    error.code = 'EACCES';
+    (readFileSync as MockedFunction<typeof readFileSync>).mockImplementation(
+      () => {
+        throw error;
+      }
+    );
+
+    expect(() => getFileContents('restricted.txt')).toThrow(
+      /Permission denied/
+    );
+  });
+
+  it('should throw error with descriptive message when path is directory', () => {
+    const error = new Error('Is a directory') as NodeJS.ErrnoException;
+    error.code = 'EISDIR';
+    (readFileSync as MockedFunction<typeof readFileSync>).mockImplementation(
+      () => {
+        throw error;
+      }
+    );
+
+    expect(() => getFileContents('some-dir')).toThrow(/Is a directory/);
+  });
+
+  it('should throw generic error for unknown error codes', () => {
+    const error = new Error(
+      'Unknown filesystem error'
+    ) as NodeJS.ErrnoException;
+    error.code = 'UNKNOWN';
+    (readFileSync as MockedFunction<typeof readFileSync>).mockImplementation(
+      () => {
+        throw error;
+      }
+    );
+
+    expect(() => getFileContents('file.txt')).toThrow(
+      /Unknown filesystem error/
+    );
+  });
+});

package/cli/tests/version-integration.test.ts

@@ -0,0 +1,39 @@
+import { describe, it, expect, vi, type MockedFunction } from 'vitest';
+import { readFileSync } from 'fs';
+
+// Mock fs at the module level so both files use the same mock
+vi.mock('fs', () => ({
+  readFileSync: vi.fn(),
+}));
+
+describe('getVersion integration with getFileContents', () => {
+  it('should successfully integrate getFileContents and JSON parsing', async () => {
+    const mockPackageJson = JSON.stringify({
+      name: 'test-package',
+      version: '1.2.3',
+      description: 'Test package',
+      dependencies: {
+        'some-package': '^1.0.0',
+      },
+    });
+
+    (readFileSync as MockedFunction<typeof readFileSync>).mockReturnValue(
+      mockPackageJson
+    );
+
+    // Import after mocking to ensure the mock is applied
+    const { getVersion } = await import('../utils/version.ts');
+
+    const version = getVersion();
+
+    // Verify the integration chain works:
+    // getVersion -> getFileContents -> readFileSync -> JSON.parse -> return version
+    expect(version).toBe('1.2.3');
+
+    // Verify that getFileContents was called with the correct relative path
+    expect(readFileSync).toHaveBeenCalledWith(
+      expect.stringContaining('package.json'),
+      'utf8'
+    );
+  });
+});

package/cli/utils/cli-metadata.ts

@@ -0,0 +1,9 @@
+export interface CLIMetadata {
+  name: string;
+  description: string;
+}
+
+export const CLI_metadata: CLIMetadata = {
+  name: 'hscl',
+  description: 'HubSpot CMS Component Library CLI',
+};

package/cli/utils/component-naming.ts

@@ -0,0 +1,76 @@
+import { logWarning } from '../utils/logging.js';
+
+// Validation functions
+export const validatePascalCase = (
+  value?: string,
+  fallbackValue: string | null = null
+): string | true => {
+  const finalValue = value || fallbackValue;
+  if (!finalValue) return 'Component name is required';
+  if (!/^[A-Z][a-zA-Z0-9]*$/.test(finalValue)) {
+    return 'Component name must be PascalCase (e.g., MyComponent)';
+  }
+  return true;
+};
+
+export const validateAndFixPrefix = (customName: string): string => {
+  let fixedName = customName;
+
+  // Convert to PascalCase: capitalize letters after spaces, hyphens, and underscores, then remove the separators
+  fixedName = fixedName.replace(/[ \-_]+(.)/g, (_, letter) =>
+    letter.toUpperCase()
+  );
+
+  // Fix lowercase first letter
+  if (fixedName[0]) {
+    fixedName = fixedName[0].toUpperCase() + fixedName.slice(1);
+  }
+
+  // Show message if anything was changed
+  if (fixedName !== customName) {
+    logWarning(
+      `⚠️ Your custom name doesn't meet React naming standards. We fixed it for you: "${customName}" → "${fixedName}"`
+    );
+  }
+
+  return fixedName;
+};
+
+// String similarity function using Levenshtein distance
+export function calculateTextSimilarity(str1: string, str2: string): number {
+  const longer = str1.length > str2.length ? str1 : str2;
+  const shorter = str1.length > str2.length ? str2 : str1;
+
+  if (longer.length === 0) return 1.0;
+
+  const textDiff = getTextDifference(longer, shorter);
+  return (longer.length - textDiff) / longer.length;
+}
+
+function getTextDifference(str1: string, str2: string): number {
+  const matrix: number[][] = [];
+
+  for (let i = 0; i <= str2.length; i++) {
+    matrix[i] = [i];
+  }
+
+  for (let j = 0; j <= str1.length; j++) {
+    matrix[0][j] = j;
+  }
+
+  for (let i = 1; i <= str2.length; i++) {
+    for (let j = 1; j <= str1.length; j++) {
+      if (str2.charAt(i - 1) === str1.charAt(j - 1)) {
+        matrix[i][j] = matrix[i - 1][j - 1];
+      } else {
+        matrix[i][j] = Math.min(
+          matrix[i - 1][j - 1] + 1,
+          matrix[i][j - 1] + 1,
+          matrix[i - 1][j] + 1
+        );
+      }
+    }
+  }
+
+  return matrix[str2.length][str1.length];
+}

package/cli/utils/components.ts

@@ -0,0 +1,74 @@
+import { promises as fs } from 'fs';
+import { fileURLToPath } from 'url';
+import path from 'path';
+import {
+  calculateTextSimilarity,
+  validatePascalCase,
+} from './component-naming.js';
+import { logError } from './logging.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+export async function getAvailableComponents(): Promise<string[]> {
+  const componentsDir = path.join(
+    __dirname,
+    '../../components/componentLibrary'
+  );
+  const entries = await fs.readdir(componentsDir, { withFileTypes: true });
+
+  // only want to return components (ignoring util/type/etc directories)
+  return entries
+    .filter(entry => entry.isDirectory())
+    .filter(entry => validatePascalCase(entry.name) === true)
+    .map(entry => entry.name)
+    .sort();
+}
+
+export async function findComponentName(
+  components: string[],
+  sourceComponent: string
+): Promise<string | null> {
+  // Find exact match first, then case-insensitive match
+  const exactMatch = components.find(
+    component => component === sourceComponent
+  );
+  const caseInsensitiveMatch = components.find(
+    component => component.toLowerCase() === sourceComponent.toLowerCase()
+  );
+
+  return exactMatch || caseInsensitiveMatch || null;
+}
+
+export async function validateComponentExists(
+  sourceComponent: string
+): Promise<boolean> {
+  const components = await getAvailableComponents();
+  const foundComponent = await findComponentName(components, sourceComponent);
+
+  if (foundComponent) return true;
+
+  const componentNotFoundMessage = `❌ Component "${sourceComponent}" not found.`;
+
+  const suggestions = components
+    .map(component => ({
+      name: component,
+      similarity: calculateTextSimilarity(
+        sourceComponent.toLowerCase(),
+        component.toLowerCase()
+      ),
+    }))
+    .filter(item => item.similarity > 0.3) // Only show if 30% similar
+    .sort((a, b) => b.similarity - a.similarity)
+    .slice(0, 3) // Top 3 suggestions
+    .map(item => item.name);
+
+  if (suggestions.length > 0) {
+    logError(
+      `${componentNotFoundMessage} Did you mean: ${suggestions.join(', ')}?`
+    );
+  } else {
+    logError(`${componentNotFoundMessage}`);
+  }
+  return false;
+}