sharetribe-cli 1.15.0

package/src/util/help-formatter.ts

@@ -0,0 +1,266 @@
+/**
+ * Custom help formatter to match flex-cli output exactly
+ */
+
+import { Command, Help } from 'commander';
+import chalk from 'chalk';
+
+/**
+ * Formats help text to match flex-cli style
+ *
+ * flex-cli format:
+ * - Description (no label)
+ * - VERSION section (for main help only)
+ * - USAGE section
+ * - COMMANDS section (flattened list of all leaf commands)
+ * - OPTIONS section (for subcommands only, not main)
+ * - Subcommand help instructions
+ *
+ * @param cmd - Commander command instance
+ * @returns Formatted help text matching flex-cli
+ */
+export function formatHelp(cmd: Command): string {
+  const parts: string[] = [];
+  const isRootCommand = !cmd.parent;
+
+  // Description (no label, just the text)
+  const description = cmd.description();
+  if (description) {
+    parts.push(description);
+    parts.push('');
+  }
+
+  // VERSION section (only for root command)
+  if (isRootCommand) {
+    const version = cmd.version();
+    if (version) {
+      parts.push('VERSION');
+      parts.push(`  ${version}`);
+      parts.push('');
+    }
+  }
+
+  // USAGE section
+  parts.push('USAGE');
+  const usage = formatUsage(cmd);
+  parts.push(`  $ ${usage}`);
+  parts.push('');
+
+  // COMMANDS section
+  // Note: If command has an action (options), don't show COMMANDS section (like flex-cli)
+  const allCommands = collectAllLeafCommands(cmd);
+  const hasAction = cmd.options.length > 0 && !isRootCommand;
+
+  if (allCommands.length > 0 && !hasAction) {
+    parts.push('COMMANDS');
+
+    // Calculate max command name length for alignment
+    const maxLength = Math.max(...allCommands.map(c => c.name.length));
+
+    for (const cmdInfo of allCommands) {
+      const paddedName = cmdInfo.name.padEnd(maxLength + 2);
+      parts.push(`  ${paddedName}${cmdInfo.description}`);
+    }
+    parts.push('');
+  }
+
+  // OPTIONS section (only for subcommands, not root)
+  if (!isRootCommand) {
+    const options = cmd.options;
+    if (options.length > 0) {
+      parts.push('OPTIONS');
+
+      // Calculate max option flags length for alignment
+      const maxFlagsLength = Math.max(...options.map(opt => formatOptionFlags(opt).length));
+
+      for (const opt of options) {
+        const flags = formatOptionFlags(opt);
+        const paddedFlags = flags.padEnd(maxFlagsLength + 2);
+        const desc = opt.description || '';
+        parts.push(`  ${paddedFlags}${desc}`);
+      }
+      parts.push('');
+    }
+  }
+
+  // Subcommand help instructions (only for main and group commands without actions)
+  if (allCommands.length > 0 && !hasAction) {
+    parts.push('Subcommand help:');
+    const cmdName = getCommandName(cmd);
+    parts.push(`  $ ${cmdName} help [COMMAND]`);
+  }
+
+  // Always add empty line at end to match flex-cli
+  parts.push('');
+
+  return parts.join('\n');
+}
+
+/**
+ * Recursively collects all commands (both parent and leaf commands)
+ *
+ * flex-cli shows ALL commands, including parent commands that have their own actions
+ * Example: both "events" and "events tail" are shown
+ *
+ * @param cmd - Commander command instance
+ * @returns Array of command info objects with name and description
+ */
+function collectAllLeafCommands(cmd: Command): Array<{ name: string; description: string }> {
+  const results: Array<{ name: string; description: string }> = [];
+  const commands = cmd.commands.filter(c => !c._hidden && c.name() !== 'help');
+
+  for (const subCmd of commands) {
+    const fullName = getCommandFullName(subCmd);
+    const subCommands = subCmd.commands.filter(c => !c._hidden);
+
+    // Add this command if it has an action or description
+    if (subCmd.description()) {
+      results.push({
+        name: fullName,
+        description: subCmd.description() || ''
+      });
+    }
+
+    // If it has subcommands, recurse and add those too
+    if (subCommands.length > 0) {
+      const subResults = collectAllLeafCommands(subCmd);
+      for (const sub of subResults) {
+        results.push(sub);
+      }
+    }
+  }
+
+  // Add "help" command at the beginning if this is root
+  if (!cmd.parent) {
+    results.unshift({
+      name: 'help',
+      description: 'display help for Flex CLI'
+    });
+  }
+
+  // Sort alphabetically by command name
+  results.sort((a, b) => a.name.localeCompare(b.name));
+
+  return results;
+}
+
+/**
+ * Gets the command name for usage (flex-cli vs sharetribe-cli)
+ *
+ * @param cmd - Commander command instance
+ * @returns Command name (e.g., "sharetribe-cli" or "sharetribe-cli process")
+ */
+function getCommandName(cmd: Command): string {
+  const names: string[] = [];
+  let current: Command | null = cmd;
+
+  while (current) {
+    if (current.name()) {
+      names.unshift(current.name());
+    }
+    current = current.parent;
+  }
+
+  // Replace first name with "sharetribe-cli" (or "flex-cli" for reference)
+  if (names.length > 0) {
+    names[0] = 'sharetribe-cli';
+  }
+
+  return names.join(' ');
+}
+
+/**
+ * Formats the USAGE line
+ *
+ * @param cmd - Commander command instance
+ * @returns Usage string (e.g., "sharetribe-cli [COMMAND]" or "sharetribe-cli process list")
+ */
+function formatUsage(cmd: Command): string {
+  const cmdName = getCommandName(cmd);
+  const commands = cmd.commands.filter(c => !c._hidden);
+  const hasOptions = cmd.options.length > 0;
+  const isRoot = !cmd.parent;
+
+  // Root command always shows [COMMAND] if it has subcommands
+  if (isRoot && commands.length > 0) {
+    return `${cmdName} [COMMAND]`;
+  }
+
+  // If command has options (its own action), don't show [COMMAND] even if it has subcommands
+  // This matches flex-cli behavior for commands like "process" which have both action and subcommands
+  if (commands.length > 0 && !hasOptions) {
+    // Has subcommands but no action
+    return `${cmdName} [COMMAND]`;
+  } else {
+    // Leaf command or command with action - just show the command path
+    return cmdName;
+  }
+}
+
+/**
+ * Gets the full command name including parent path
+ *
+ * @param cmd - Commander command instance
+ * @returns Full command name (e.g., "process list" or "events tail")
+ */
+function getCommandFullName(cmd: Command): string {
+  const names: string[] = [];
+  let current: Command | null = cmd;
+
+  while (current && current.parent) {
+    if (current.name()) {
+      names.unshift(current.name());
+    }
+    current = current.parent;
+  }
+
+  return names.join(' ');
+}
+
+/**
+ * Formats option flags for display
+ *
+ * @param opt - Commander option instance
+ * @returns Formatted flags string (e.g., "-m, --marketplace=MARKETPLACE_ID")
+ */
+function formatOptionFlags(opt: any): string {
+  // Commander option flags are in opt.flags (e.g., "-m, --marketplace <MARKETPLACE_ID>")
+  // We need to parse and reformat this to match flex-cli style
+  const flagsStr = opt.flags || '';
+
+  // Parse the flags string
+  // Format: "-m, --marketplace <VALUE>" or "--flag" or "-f"
+  const parts = flagsStr.split(/,\s*/);
+  const formatted: string[] = [];
+
+  for (const part of parts) {
+    const trimmed = part.trim();
+
+    // Check if it has a value placeholder (angle brackets or square brackets)
+    const valueMatch = trimmed.match(/^((?:-{1,2}[\w-]+))\s*[<\[]([^\]>]+)[\]>]/);
+    if (valueMatch) {
+      // Has a value: "-m <MARKETPLACE_ID>" or "--marketplace <MARKETPLACE_ID>"
+      const flag = valueMatch[1];
+      const valueName = valueMatch[2];
+      formatted.push(`${flag}=${valueName}`);
+    } else {
+      // No value: just the flag
+      formatted.push(trimmed);
+    }
+  }
+
+  return formatted.join(', ');
+}
+
+/**
+ * Configures Commander.js to use custom help formatter
+ *
+ * @param program - Commander program instance
+ */
+export function configureHelp(program: Command): void {
+  program.configureHelp({
+    formatHelp: (cmd: Command, helper: Help) => {
+      return formatHelp(cmd);
+    }
+  });
+}

package/src/util/output.ts

@@ -0,0 +1,83 @@
+/**
+ * Output formatting utilities
+ *
+ * Must match flex-cli output format exactly
+ */
+
+import chalk from 'chalk';
+
+/**
+ * Prints a table with headers and rows
+ *
+ * Matches flex-cli table formatting exactly
+ */
+export function printTable(headers: string[], rows: Array<Record<string, string>>): void {
+  if (rows.length === 0) {
+    return;
+  }
+
+  // Calculate column widths
+  // flex-cli uses keywords (e.g., :version) which when stringified include the ':' prefix
+  // To match flex-cli widths, we add 1 to header length to simulate the ':' prefix
+  const widths: Record<string, number> = {};
+  for (const header of headers) {
+    widths[header] = header.length + 1;  // +1 to match flex-cli keyword string behavior
+  }
+
+  for (const row of rows) {
+    for (const header of headers) {
+      const value = row[header] || '';
+      widths[header] = Math.max(widths[header] || 0, value.length);
+    }
+  }
+
+  // Print empty line before table (like flex-cli)
+  console.log('');
+
+  // Print header with bold formatting
+  // flex-cli format: each column padded to (max_width + 1), with single space separator between columns
+  // Last column: padding but no separator (interpose doesn't add separator after last element)
+  const headerParts = headers.map((h, i) => {
+    const width = widths[h] || 0;
+    const padded = h.padEnd(width + 1);
+    return i === headers.length - 1 ? padded : padded + ' ';
+  });
+  const headerRow = headerParts.join('');
+  console.log(chalk.bold.black(headerRow));
+
+  // Print rows with same formatting
+  for (const row of rows) {
+    const rowParts = headers.map((h, i) => {
+      const value = row[h] || '';
+      const width = widths[h] || 0;
+      const padded = value.padEnd(width + 1);
+      return i === headers.length - 1 ? padded : padded + ' ';
+    });
+    const rowStr = rowParts.join('');
+    console.log(rowStr);
+  }
+
+  // Print empty line after table (like flex-cli)
+  console.log('');
+}
+
+/**
+ * Prints an error message
+ */
+export function printError(message: string): void {
+  console.error(chalk.red(`Error: ${message}`));
+}
+
+/**
+ * Prints a success message
+ */
+export function printSuccess(message: string): void {
+  console.log(chalk.green(message));
+}
+
+/**
+ * Prints a warning message
+ */
+export function printWarning(message: string): void {
+  console.log(chalk.yellow(`Warning: ${message}`));
+}

package/test/help-comparison.test.ts

@@ -0,0 +1,255 @@
+/**
+ * Comprehensive help output comparison tests
+ *
+ * Tests that help output matches flex-cli for all commands
+ */
+
+import { describe, it, expect } from 'vitest';
+import { execSync } from 'child_process';
+
+/**
+ * Executes a CLI command and returns output
+ */
+function runCli(command: string, cli: 'flex' | 'sharetribe'): string {
+  const cliName = cli === 'flex' ? 'flex-cli' : 'sharetribe-cli';
+  try {
+    return execSync(`${cliName} ${command}`, {
+      encoding: 'utf-8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+  } catch (error) {
+    if (error instanceof Error && 'stdout' in error && 'stderr' in error) {
+      const stdout = (error as any).stdout || '';
+      const stderr = (error as any).stderr || '';
+      return stdout + stderr;
+    }
+    throw error;
+  }
+}
+
+/**
+ * Normalizes help output for comparison (removes CLI name differences)
+ */
+function normalizeHelp(output: string, cliName: string): string {
+  return output
+    .replace(new RegExp(cliName, 'g'), 'CLI')
+    .replace(/\s+$/gm, ''); // Trim trailing spaces per line
+}
+
+/**
+ * Compares help structure (sections present, not exact content)
+ */
+function compareHelpStructure(flexOutput: string, shareOutput: string, cmdName: string) {
+  // Both should have description
+  const flexLines = flexOutput.split('\n');
+  const shareLines = shareOutput.split('\n');
+
+  // First line should be description
+  expect(shareLines[0]).toBeTruthy();
+  expect(shareLines[0]).not.toMatch(/^USAGE|^OPTIONS|^COMMANDS/);
+
+  // Should have USAGE section
+  expect(shareOutput).toContain('USAGE');
+
+  // Check if flex has OPTIONS
+  if (flexOutput.includes('OPTIONS')) {
+    expect(shareOutput).toContain('OPTIONS');
+  }
+
+  // Check if flex has COMMANDS
+  if (flexOutput.includes('COMMANDS')) {
+    expect(shareOutput).toContain('COMMANDS');
+  }
+}
+
+describe('Help Comparison Tests', () => {
+  describe('Main help', () => {
+    it('has same structure as flex-cli', () => {
+      const flexOutput = runCli('--help', 'flex');
+      const shareOutput = runCli('--help', 'sharetribe');
+
+      expect(shareOutput).toContain('VERSION');
+      expect(shareOutput).toContain('USAGE');
+      expect(shareOutput).toContain('COMMANDS');
+      expect(shareOutput).toContain('Subcommand help:');
+
+      // Should NOT have OPTIONS in main help
+      const lines = shareOutput.split('\n');
+      const commandsIndex = lines.findIndex(l => l === 'COMMANDS');
+      const subcommandIndex = lines.findIndex(l => l.startsWith('Subcommand help:'));
+      const betweenLines = lines.slice(commandsIndex, subcommandIndex);
+      expect(betweenLines.some(l => l === 'OPTIONS')).toBe(false);
+    });
+
+    it('commands are alphabetically sorted', () => {
+      const shareOutput = runCli('--help', 'sharetribe');
+      const lines = shareOutput.split('\n');
+      const commandsStartIndex = lines.findIndex(l => l === 'COMMANDS');
+      const commandLines = lines.slice(commandsStartIndex + 1).filter(l => l.match(/^\s+\w/));
+
+      const commandNames = commandLines.map(l => l.trim().split(/\s+/)[0]);
+      const sortedNames = [...commandNames].sort();
+
+      expect(commandNames).toEqual(sortedNames);
+    });
+
+    it('ends with empty line', () => {
+      const shareOutput = runCli('--help', 'sharetribe');
+      expect(shareOutput).toMatch(/\n$/);
+      expect(shareOutput).toMatch(/\n\n$/);
+    });
+  });
+
+  describe('help process', () => {
+    it('matches flex-cli structure', () => {
+      const flexOutput = runCli('help process', 'flex');
+      const shareOutput = runCli('help process', 'sharetribe');
+
+      compareHelpStructure(flexOutput, shareOutput, 'process');
+
+      // Should have OPTIONS (process has --path and --transition options)
+      expect(shareOutput).toContain('OPTIONS');
+      expect(shareOutput).toContain('--path');
+      expect(shareOutput).toContain('--transition');
+    });
+
+    it('has correct description', () => {
+      const shareOutput = runCli('help process', 'sharetribe');
+      const lines = shareOutput.split('\n');
+      expect(lines[0]).toBe('describe a process file');
+    });
+
+    it('has correct usage', () => {
+      const shareOutput = runCli('help process', 'sharetribe');
+      expect(shareOutput).toMatch(/\$ sharetribe-cli process$/m);
+    });
+  });
+
+  describe('help process list', () => {
+    it('matches flex-cli structure', () => {
+      const flexOutput = runCli('help process list', 'flex');
+      const shareOutput = runCli('help process list', 'sharetribe');
+
+      compareHelpStructure(flexOutput, shareOutput, 'process list');
+
+      expect(shareOutput).toContain('OPTIONS');
+      expect(shareOutput).toContain('--process');
+      expect(shareOutput).toContain('--marketplace');
+    });
+
+    it('has correct description', () => {
+      const shareOutput = runCli('help process list', 'sharetribe');
+      expect(shareOutput).toMatch(/^list all transaction processes/);
+    });
+  });
+
+  describe('help events', () => {
+    it('matches flex-cli structure', () => {
+      const flexOutput = runCli('help events', 'flex');
+      const shareOutput = runCli('help events', 'sharetribe');
+
+      compareHelpStructure(flexOutput, shareOutput, 'events');
+
+      expect(shareOutput).toContain('OPTIONS');
+    });
+
+    it('has correct description', () => {
+      const shareOutput = runCli('help events', 'sharetribe');
+      expect(shareOutput).toMatch(/^Get a list of events\./);
+    });
+  });
+
+  describe('help search', () => {
+    it('matches flex-cli structure', () => {
+      const flexOutput = runCli('help search', 'flex');
+      const shareOutput = runCli('help search', 'sharetribe');
+
+      compareHelpStructure(flexOutput, shareOutput, 'search');
+    });
+
+    it('has correct description', () => {
+      const shareOutput = runCli('help search', 'sharetribe');
+      expect(shareOutput).toMatch(/^list all search schemas/);
+    });
+  });
+
+  describe('help notifications', () => {
+    it('has correct structure', () => {
+      const shareOutput = runCli('help notifications', 'sharetribe');
+
+      expect(shareOutput).toContain('USAGE');
+      expect(shareOutput).toContain('COMMANDS');
+    });
+  });
+
+  describe('help login', () => {
+    it('has correct structure', () => {
+      const shareOutput = runCli('help login', 'sharetribe');
+
+      expect(shareOutput).toContain('USAGE');
+      expect(shareOutput).toContain('$ sharetribe-cli login');
+    });
+  });
+
+  describe('help logout', () => {
+    it('has correct structure', () => {
+      const shareOutput = runCli('help logout', 'sharetribe');
+
+      expect(shareOutput).toContain('USAGE');
+      expect(shareOutput).toContain('$ sharetribe-cli logout');
+    });
+  });
+
+  describe('help version', () => {
+    it('has correct structure', () => {
+      const shareOutput = runCli('help version', 'sharetribe');
+
+      expect(shareOutput).toContain('USAGE');
+      expect(shareOutput).toContain('$ sharetribe-cli version');
+    });
+  });
+
+  describe('All help commands have consistent format', () => {
+    const commands = [
+      'help',
+      'events',
+      'events tail',
+      'login',
+      'logout',
+      'process',
+      'process list',
+      'process create',
+      'process push',
+      'process pull',
+      'process create-alias',
+      'process update-alias',
+      'process delete-alias',
+      'search',
+      'search set',
+      'search unset',
+      'notifications',
+      'notifications preview',
+      'notifications send',
+      'stripe',
+      'stripe update-version',
+      'version',
+    ];
+
+    commands.forEach(cmd => {
+      it(`help ${cmd} - has description and USAGE`, () => {
+        const output = runCli(`help ${cmd}`, 'sharetribe');
+        const lines = output.split('\n').filter(l => l.trim());
+
+        // Should have at least description and USAGE
+        expect(lines.length).toBeGreaterThan(2);
+        expect(output).toContain('USAGE');
+        expect(output).toMatch(/\$ sharetribe-cli/);
+      });
+
+      it(`help ${cmd} - ends with empty line`, () => {
+        const output = runCli(`help ${cmd}`, 'sharetribe');
+        expect(output).toMatch(/\n\n$/);
+      });
+    });
+  });
+});

package/test/process-builder.test.ts

@@ -0,0 +1,14 @@
+/**
+ * Tests for process commands
+ */
+
+import { describe, it, expect } from 'vitest';
+import { parseProcessFile } from 'sharetribe-flex-build-sdk';
+
+describe('edn-process', () => {
+  it('should parse process definition structure', () => {
+    // This would test actual EDN parsing
+    // For now, verify the function exists and has correct signature
+    expect(typeof parseProcessFile).toBe('function');
+  });
+});