feat: add tcx2webvtt cli script

Author: limulus

PLAN.md

@@ -9,8 +9,8 @@ Pro XML export) to omit parts of the output and ensure synchronization with an e
 
 - [x] Set up vitest browser testing that will enable testing of WebVTT output
 - [x] Class to generate WebVTT file from array of `Sample`s
-- [] Create a CLI Node.js executable that takes the XML file as an argument and outputs
-  WebVTT.
+- [x] Create a CLI Node.js executable that takes the XML file as an argument and outputs
+      WebVTT.
 - [] Parse timecode data from a Final Cut Pro XML export
 - [] Create a class that uses the timecode info from the FCP XML and creates a list of
   datetime intervals that the video project includes

fixtures/invalid.tcx

@@ -0,0 +1 @@
+<?xml version="1.0"?><unclosed

package-lock.json

@@ -16,6 +16,9 @@
     "dist",
     "src"
   ],
+  "bin": {
+    "tcx2webvtt": "dist/bin/tcx2webvtt.js"
+  },
   "type": "module",
   "scripts": {
     "prebuild": "npm run clean",

package.json

@@ -0,0 +1,109 @@
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { describe, it, expect, beforeEach, vi } from 'vitest'
+
+import { main, ProcessLike } from './tcx2webvtt.js'
+
+const __dirname = fileURLToPath(new URL('.', import.meta.url))
+
+describe('tcx2webvtt CLI', () => {
+  let mockProcess: ProcessLike
+  let stdout: string
+  let stderr: string
+
+  beforeEach(async () => {
+    // Reset output capture variables
+    stdout = ''
+    stderr = ''
+
+    // Mock process with string buffers
+    mockProcess = {
+      argv: ['node', 'tcx2webvtt.js'],
+      stdout: {
+        write(data: string) {
+          stdout += data
+        },
+      },
+      stderr: {
+        write(data: string) {
+          stderr += data
+        },
+      },
+      exit: vi.fn(),
+    }
+  })
+
+  it('should display help when --help flag is used', async () => {
+    mockProcess.argv.push('--help')
+
+    await main(mockProcess)
+
+    expect(stdout).toContain('Usage:')
+    expect(stdout).toContain('Options:')
+    expect(stdout).toContain('--help')
+    expect(stdout).toContain('--version')
+    expect(mockProcess.exit).toHaveBeenCalledWith(0)
+  })
+
+  it('should display version when --version flag is used', async () => {
+    mockProcess.argv.push('--version')
+
+    await main(mockProcess)
+
+    expect(stdout).toMatch(/\d+\.\d+\.\d+/)
+    expect(mockProcess.exit).toHaveBeenCalledWith(0)
+  })
+
+  it('should require an input file', async () => {
+    await main(mockProcess)
+
+    expect(stderr).toContain('Input file is required')
+    expect(mockProcess.exit).toHaveBeenCalledWith(1)
+  })
+
+  it('should check if input file exists', async () => {
+    mockProcess.argv.push('nonexistent.tcx')
+
+    await main(mockProcess)
+
+    expect(stderr).toContain('Input file does not exist')
+    expect(mockProcess.exit).toHaveBeenCalledWith(1)
+  })
+
+  it('should convert TCX to WebVTT and output to stdout', async () => {
+    const fixtureFile = join(__dirname, '../../fixtures/concept2.tcx')
+    mockProcess.argv.push(fixtureFile)
+
+    await main(mockProcess)
+
+    // Verify the output is WebVTT format
+    expect(stdout).toContain('WEBVTT')
+    expect(stdout).toContain('-->')
+    expect(stdout).toContain('"metric"')
+    expect(mockProcess.exit).not.toHaveBeenCalled()
+  })
+
+  it('should handle invalid TCX files', async () => {
+    const invalidXmlFile = join(__dirname, '../../fixtures/invalid.tcx')
+
+    mockProcess.argv.push(invalidXmlFile)
+
+    await main(mockProcess)
+
+    expect(stderr).not.toBe('')
+    expect(mockProcess.exit).toHaveBeenCalledWith(1)
+  })
+
+  it('should handle TCX files with no trackpoints', async () => {
+    // Use the fixture with no activities
+    const fixtureFile = join(__dirname, '../../fixtures/no-activities.tcx')
+
+    mockProcess.argv.push(fixtureFile)
+
+    await main(mockProcess)
+
+    // Should still output a valid WebVTT header even with no samples
+    expect(stdout).toBe('WEBVTT')
+    expect(mockProcess.exit).not.toHaveBeenCalled()
+  })
+})

src/bin/tcx2webvtt.spec.ts

@@ -0,0 +1,111 @@
+#!/usr/bin/env node
+
+import { existsSync } from 'node:fs'
+import { readFile } from 'node:fs/promises'
+import { join, dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { parseArgs } from 'node:util'
+
+import { TCXReader } from '../lib/tcx-reader.js'
+import { WebVTTGenerator } from '../lib/webvtt-generator.js'
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = dirname(__filename)
+
+function displayHelp(stdout: { write: (data: string) => void }) {
+  stdout.write(`
+Usage: tcx2webvtt [options] <input-file>
+
+Convert TCX workout files to WebVTT format with embedded JSON metadata.
+
+Options:
+  -h, --help                Display this help message
+  -v, --version             Display version information
+
+Examples:
+  tcx2webvtt workout.tcx > workout.vtt
+  `)
+}
+
+export interface ProcessLike {
+  argv: string[]
+  stdout: {
+    write: (data: string) => void
+  }
+  stderr: {
+    write: (data: string) => void
+  }
+  exit: (code: number) => void
+}
+
+export async function main(proc: ProcessLike) {
+  try {
+    // Parse command line arguments
+    const { values, positionals } = parseArgs({
+      args: proc.argv.slice(2),
+      options: {
+        help: { type: 'boolean', short: 'h' },
+        version: { type: 'boolean', short: 'v' },
+      },
+      allowPositionals: true,
+    })
+
+    // Display help
+    if (values.help) {
+      displayHelp(proc.stdout)
+      proc.exit(0)
+    }
+
+    // Display version
+    if (values.version) {
+      const packagePath = join(__dirname, '../..', 'package.json')
+      const packageData = JSON.parse(await readFile(packagePath, 'utf-8'))
+      proc.stdout.write(packageData.version)
+      proc.exit(0)
+    }
+
+    // Check if input file is provided
+    if (positionals.length === 0) {
+      proc.stderr.write('Error: Input file is required\n')
+      displayHelp(proc.stdout)
+      proc.exit(1)
+    }
+
+    const inputFile = positionals[0]
+
+    // Check if input file exists
+    if (!existsSync(inputFile)) {
+      proc.stderr.write(`Error: Input file does not exist: ${inputFile}\n`)
+      proc.exit(1)
+    }
+
+    // Read TCX file
+    const tcxContent = await readFile(inputFile, 'utf-8')
+
+    try {
+      // Parse TCX
+      const tcxReader = new TCXReader(tcxContent)
+      const samples = tcxReader.getSamples()
+
+      // Generate WebVTT
+      const webvttGenerator = new WebVTTGenerator()
+      const webvttOutput = webvttGenerator.generate(samples)
+
+      // Output to stdout
+      proc.stdout.write(webvttOutput)
+    } catch (error) {
+      // Handle any processing errors
+      proc.stderr.write(`Error processing file: ${error}\n`)
+      proc.exit(1)
+    }
+  } catch (error) {
+    proc.stderr.write(`Error: ${error}\n`)
+    proc.exit(1)
+  }
+}
+
+/* c8 ignore start */
+if (fileURLToPath(import.meta.url) === process.argv[1]) {
+  await main(process)
+}
+/* c8 ignore stop */