@pep/term-deck 1.0.10

package/src/cli/__tests__/errors.test.ts

@@ -0,0 +1,201 @@
+/**
+ * Tests for CLI error handling
+ */
+
+import { describe, test, expect, mock, spyOn, beforeEach, afterEach } from 'bun:test';
+import { handleError } from '../errors.js';
+import { ValidationError } from '../../schemas/validation.js';
+import { SlideParseError, DeckLoadError } from '../../core/slide.js';
+import { ThemeError } from '../../core/theme.js';
+
+describe('handleError', () => {
+  let consoleErrorSpy: ReturnType<typeof spyOn>;
+  let processExitSpy: ReturnType<typeof spyOn>;
+  let originalDebug: string | undefined;
+
+  beforeEach(() => {
+    consoleErrorSpy = spyOn(console, 'error').mockImplementation(() => {});
+    processExitSpy = spyOn(process, 'exit').mockImplementation(
+      (() => {}) as never,
+    );
+    originalDebug = process.env.DEBUG;
+  });
+
+  afterEach(() => {
+    consoleErrorSpy.mockRestore();
+    processExitSpy.mockRestore();
+    process.env.DEBUG = originalDebug;
+  });
+
+  test('handles ValidationError', () => {
+    const error = new ValidationError('Invalid theme configuration');
+
+    handleError(error);
+
+    expect(consoleErrorSpy).toHaveBeenCalledWith(
+      expect.stringContaining('Invalid theme configuration'),
+    );
+    expect(processExitSpy).toHaveBeenCalledWith(1);
+  });
+
+  test('handles SlideParseError', () => {
+    const cause = new Error('Missing title field');
+    const error = new SlideParseError('Invalid frontmatter', 'slides/01.md', cause);
+
+    handleError(error);
+
+    expect(consoleErrorSpy).toHaveBeenCalledWith(
+      expect.stringContaining('slides/01.md'),
+    );
+    expect(consoleErrorSpy).toHaveBeenCalledWith(
+      expect.stringContaining('Invalid frontmatter'),
+    );
+    expect(consoleErrorSpy).toHaveBeenCalledWith(
+      expect.stringContaining('Missing title field'),
+    );
+    expect(processExitSpy).toHaveBeenCalledWith(1);
+  });
+
+  test('handles SlideParseError without cause', () => {
+    const error = new SlideParseError('Invalid frontmatter', 'slides/02.md');
+
+    handleError(error);
+
+    expect(consoleErrorSpy).toHaveBeenCalledWith(
+      expect.stringContaining('slides/02.md'),
+    );
+    expect(processExitSpy).toHaveBeenCalledWith(1);
+  });
+
+  test('handles DeckLoadError', () => {
+    const error = new DeckLoadError('No slides found', './slides');
+
+    handleError(error);
+
+    expect(consoleErrorSpy).toHaveBeenCalledWith(
+      expect.stringContaining('./slides'),
+    );
+    expect(consoleErrorSpy).toHaveBeenCalledWith(
+      expect.stringContaining('No slides found'),
+    );
+    expect(processExitSpy).toHaveBeenCalledWith(1);
+  });
+
+  test('handles ThemeError', () => {
+    const error = new ThemeError('Invalid color format', 'custom-theme');
+
+    handleError(error);
+
+    expect(consoleErrorSpy).toHaveBeenCalledWith(
+      expect.stringContaining('Theme error'),
+    );
+    expect(consoleErrorSpy).toHaveBeenCalledWith(
+      expect.stringContaining('Invalid color format'),
+    );
+    expect(processExitSpy).toHaveBeenCalledWith(1);
+  });
+
+  test('handles ENOENT errors', () => {
+    const error = new Error('ENOENT: no such file or directory');
+
+    handleError(error);
+
+    expect(consoleErrorSpy).toHaveBeenCalledWith(
+      expect.stringContaining('File or directory not found'),
+    );
+    expect(processExitSpy).toHaveBeenCalledWith(1);
+  });
+
+  test('handles ffmpeg errors', () => {
+    const error = new Error('ffmpeg not found in PATH');
+
+    handleError(error);
+
+    expect(consoleErrorSpy).toHaveBeenCalledWith(
+      expect.stringContaining('ffmpeg error'),
+    );
+    expect(consoleErrorSpy).toHaveBeenCalledWith(
+      expect.stringContaining('Make sure ffmpeg is installed'),
+    );
+    expect(consoleErrorSpy).toHaveBeenCalledWith(
+      expect.stringContaining('brew install ffmpeg'),
+    );
+    expect(processExitSpy).toHaveBeenCalledWith(1);
+  });
+
+  test('handles generic errors', () => {
+    const error = new Error('Something went wrong');
+
+    handleError(error);
+
+    expect(consoleErrorSpy).toHaveBeenCalledWith(
+      expect.stringContaining('Something went wrong'),
+    );
+    expect(processExitSpy).toHaveBeenCalledWith(1);
+  });
+
+  test('shows stack trace when DEBUG is set', () => {
+    process.env.DEBUG = '1';
+    const error = new Error('Debug error');
+    error.stack = 'Error: Debug error\n  at test.ts:10:20';
+
+    handleError(error);
+
+    expect(consoleErrorSpy).toHaveBeenCalledWith(
+      expect.stringContaining('at test.ts'),
+    );
+    expect(processExitSpy).toHaveBeenCalledWith(1);
+  });
+
+  test('hides stack trace when DEBUG is not set', () => {
+    delete process.env.DEBUG;
+    const error = new Error('Regular error');
+    error.stack = 'Error: Regular error\n  at test.ts:10:20';
+
+    handleError(error);
+
+    // Should show error message
+    expect(consoleErrorSpy).toHaveBeenCalledWith(
+      expect.stringContaining('Regular error'),
+    );
+
+    // Should NOT show stack trace
+    const calls = consoleErrorSpy.mock.calls;
+    const hasStackTrace = calls.some((call) =>
+      call.some((arg) => String(arg).includes('at test.ts')),
+    );
+    expect(hasStackTrace).toBe(false);
+
+    expect(processExitSpy).toHaveBeenCalledWith(1);
+  });
+
+  test('handles unknown errors', () => {
+    const error = 'string error';
+
+    handleError(error);
+
+    expect(consoleErrorSpy).toHaveBeenCalledWith(
+      expect.stringContaining('Unknown error'),
+    );
+    expect(processExitSpy).toHaveBeenCalledWith(1);
+  });
+
+  test('exits with code 1 for all errors', () => {
+    const errors = [
+      new ValidationError('test'),
+      new SlideParseError('test', 'test.md'),
+      new DeckLoadError('test', './slides'),
+      new ThemeError('test', 'theme'),
+      new Error('ENOENT'),
+      new Error('ffmpeg'),
+      new Error('generic'),
+      'unknown',
+    ];
+
+    for (const error of errors) {
+      processExitSpy.mockClear();
+      handleError(error);
+      expect(processExitSpy).toHaveBeenCalledWith(1);
+    }
+  });
+});

package/src/cli/__tests__/help.test.ts

@@ -0,0 +1,157 @@
+/**
+ * Tests for CLI help text
+ */
+
+import { describe, test, expect } from 'bun:test';
+import { Command } from 'commander';
+import { presentCommand } from '../commands/present.js';
+import { exportCommand } from '../commands/export.js';
+import { initCommand } from '../commands/init.js';
+
+describe('CLI help text', () => {
+  test('present command has description', () => {
+    expect(presentCommand.description()).toBeTruthy();
+    expect(presentCommand.description()).toContain('present');
+  });
+
+  test('present command has all options', () => {
+    const options = presentCommand.options;
+
+    const optionNames = options.map((opt) => opt.long);
+    expect(optionNames).toContain('--start');
+    expect(optionNames).toContain('--notes');
+    expect(optionNames).toContain('--notes-tty');
+    expect(optionNames).toContain('--loop');
+  });
+
+  test('present command has short options', () => {
+    const options = presentCommand.options;
+
+    const shortNames = options.map((opt) => opt.short).filter(Boolean);
+    expect(shortNames).toContain('-s');
+    expect(shortNames).toContain('-n');
+    expect(shortNames).toContain('-l');
+  });
+
+  test('present command requires dir argument', () => {
+    const args = presentCommand.registeredArguments;
+    expect(args.length).toBeGreaterThan(0);
+    expect(args[0].name()).toBe('dir');
+    expect(args[0].required).toBe(true);
+  });
+
+  test('export command has description', () => {
+    expect(exportCommand.description()).toBeTruthy();
+    expect(exportCommand.description().toLowerCase()).toContain('export');
+  });
+
+  test('export command has all options', () => {
+    const options = exportCommand.options;
+
+    const optionNames = options.map((opt) => opt.long);
+    expect(optionNames).toContain('--output');
+    expect(optionNames).toContain('--width');
+    expect(optionNames).toContain('--height');
+    expect(optionNames).toContain('--fps');
+    expect(optionNames).toContain('--slide-time');
+    expect(optionNames).toContain('--quality');
+  });
+
+  test('export command has short options', () => {
+    const options = exportCommand.options;
+
+    const shortNames = options.map((opt) => opt.short).filter(Boolean);
+    expect(shortNames).toContain('-o');
+    expect(shortNames).toContain('-w');
+    expect(shortNames).toContain('-h');
+    expect(shortNames).toContain('-t');
+    expect(shortNames).toContain('-q');
+  });
+
+  test('export command requires dir argument', () => {
+    const args = exportCommand.registeredArguments;
+    expect(args.length).toBeGreaterThan(0);
+    expect(args[0].name()).toBe('dir');
+    expect(args[0].required).toBe(true);
+  });
+
+  test('export command requires output option', () => {
+    const outputOption = exportCommand.options.find((opt) => opt.long === '--output');
+    expect(outputOption).toBeTruthy();
+    expect(outputOption?.required).toBe(true);
+  });
+
+  test('init command has description', () => {
+    expect(initCommand.description()).toBeTruthy();
+    expect(initCommand.description()).toContain('presentation deck');
+  });
+
+  test('init command has theme option', () => {
+    const options = initCommand.options;
+
+    const optionNames = options.map((opt) => opt.long);
+    expect(optionNames).toContain('--theme');
+  });
+
+  test('init command has short theme option', () => {
+    const options = initCommand.options;
+
+    const shortNames = options.map((opt) => opt.short).filter(Boolean);
+    expect(shortNames).toContain('-t');
+  });
+
+  test('init command requires name argument', () => {
+    const args = initCommand.registeredArguments;
+    expect(args.length).toBeGreaterThan(0);
+    expect(args[0].name()).toBe('name');
+    expect(args[0].required).toBe(true);
+  });
+
+  test('main program would have version', () => {
+    // Test that version can be imported from package.json
+    const pkg = require('../../../package.json');
+    expect(pkg.version).toBeTruthy();
+    expect(typeof pkg.version).toBe('string');
+  });
+
+  test('main program would have name', () => {
+    const pkg = require('../../../package.json');
+    expect(pkg.name).toBeTruthy();
+    expect(pkg.name).toBe('term-deck');
+  });
+
+  test('all commands have help text', () => {
+    const commands = [presentCommand, exportCommand, initCommand];
+
+    for (const cmd of commands) {
+      // Commander automatically generates help
+      const helpInfo = cmd.helpInformation();
+      expect(helpInfo).toBeTruthy();
+      expect(helpInfo.length).toBeGreaterThan(0);
+    }
+  });
+
+  test('present command help includes options descriptions', () => {
+    const helpInfo = presentCommand.helpInformation();
+
+    expect(helpInfo).toContain('start');
+    expect(helpInfo).toContain('notes');
+    expect(helpInfo).toContain('loop');
+  });
+
+  test('export command help includes options descriptions', () => {
+    const helpInfo = exportCommand.helpInformation();
+
+    expect(helpInfo).toContain('output');
+    expect(helpInfo).toContain('width');
+    expect(helpInfo).toContain('height');
+    expect(helpInfo).toContain('fps');
+  });
+
+  test('init command help includes options descriptions', () => {
+    const helpInfo = initCommand.helpInformation();
+
+    expect(helpInfo).toContain('theme');
+    expect(helpInfo).toContain('name');
+  });
+});

package/src/cli/__tests__/init.test.ts

@@ -0,0 +1,110 @@
+/**
+ * Tests for init command
+ */
+
+import { describe, test, expect, beforeEach, afterEach } from 'bun:test';
+import { rmSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { initDeck } from '../commands/init.js';
+
+const TEST_DECK_NAME = 'test-deck-init';
+const TEST_DECK_PATH = join(process.cwd(), TEST_DECK_NAME);
+
+describe('initDeck', () => {
+  beforeEach(() => {
+    // Clean up if test directory exists
+    if (existsSync(TEST_DECK_PATH)) {
+      rmSync(TEST_DECK_PATH, { recursive: true, force: true });
+    }
+  });
+
+  afterEach(() => {
+    // Clean up after test
+    if (existsSync(TEST_DECK_PATH)) {
+      rmSync(TEST_DECK_PATH, { recursive: true, force: true });
+    }
+  });
+
+  test('creates deck directory structure', async () => {
+    await initDeck(TEST_DECK_NAME, 'matrix');
+
+    // Check directories
+    expect(existsSync(TEST_DECK_PATH)).toBe(true);
+    expect(existsSync(join(TEST_DECK_PATH, 'slides'))).toBe(true);
+  });
+
+  test('creates deck.config.ts', async () => {
+    await initDeck(TEST_DECK_NAME, 'matrix');
+
+    const configPath = join(TEST_DECK_PATH, 'slides', 'deck.config.ts');
+    expect(existsSync(configPath)).toBe(true);
+
+    const content = await Bun.file(configPath).text();
+    expect(content).toContain('import { defineConfig }');
+    expect(content).toContain('import matrix from');
+    expect(content).toContain(`title: '${TEST_DECK_NAME}'`);
+  });
+
+  test('creates sample slides', async () => {
+    await initDeck(TEST_DECK_NAME, 'matrix');
+
+    const slidesDir = join(TEST_DECK_PATH, 'slides');
+    expect(existsSync(join(slidesDir, '01-intro.md'))).toBe(true);
+    expect(existsSync(join(slidesDir, '02-content.md'))).toBe(true);
+    expect(existsSync(join(slidesDir, '03-end.md'))).toBe(true);
+  });
+
+  test('slides have valid frontmatter', async () => {
+    await initDeck(TEST_DECK_NAME, 'matrix');
+
+    const slidesDir = join(TEST_DECK_PATH, 'slides');
+    const slide1 = await Bun.file(join(slidesDir, '01-intro.md')).text();
+    const slide2 = await Bun.file(join(slidesDir, '02-content.md')).text();
+    const slide3 = await Bun.file(join(slidesDir, '03-end.md')).text();
+
+    // Check frontmatter structure
+    expect(slide1).toMatch(/^---\s*\ntitle:/);
+    expect(slide1).toContain('bigText:');
+    expect(slide1).toContain('gradient:');
+
+    expect(slide2).toMatch(/^---\s*\ntitle:/);
+    expect(slide2).toContain('bigText:');
+    expect(slide2).toContain('gradient:');
+
+    expect(slide3).toMatch(/^---\s*\ntitle:/);
+    expect(slide3).toContain('bigText:');
+    expect(slide3).toContain('gradient:');
+  });
+
+  test('slide 2 includes presenter notes', async () => {
+    await initDeck(TEST_DECK_NAME, 'matrix');
+
+    const slidesDir = join(TEST_DECK_PATH, 'slides');
+    const slide2 = await Bun.file(join(slidesDir, '02-content.md')).text();
+
+    expect(slide2).toContain('<!-- notes -->');
+  });
+
+  test('creates README.md', async () => {
+    await initDeck(TEST_DECK_NAME, 'matrix');
+
+    const readmePath = join(TEST_DECK_PATH, 'README.md');
+    expect(existsSync(readmePath)).toBe(true);
+
+    const content = await Bun.file(readmePath).text();
+    expect(content).toContain(`# ${TEST_DECK_NAME}`);
+    expect(content).toContain('term-deck present');
+    expect(content).toContain('term-deck export');
+    expect(content).toContain('Hotkeys');
+  });
+
+  test('uses deck name in slide titles', async () => {
+    await initDeck(TEST_DECK_NAME, 'matrix');
+
+    const slide1 = await Bun.file(
+      join(TEST_DECK_PATH, 'slides', '01-intro.md'),
+    ).text();
+
+    expect(slide1).toContain(TEST_DECK_NAME.toUpperCase());
+  });
+});

package/src/cli/commands/export.ts

@@ -0,0 +1,33 @@
+/**
+ * Export Command
+ *
+ * Exports a presentation to GIF or MP4 format.
+ */
+
+import { Command } from 'commander';
+import { exportPresentation } from '../../export/recorder.js';
+import { handleError } from '../errors.js';
+
+export const exportCommand = new Command('export')
+  .description('Export presentation to GIF or MP4')
+  .argument('<dir>', 'Slides directory')
+  .requiredOption('-o, --output <file>', 'Output file (.mp4 or .gif)')
+  .option('-w, --width <n>', 'Terminal width in characters', '120')
+  .option('-h, --height <n>', 'Terminal height in characters', '40')
+  .option('--fps <n>', 'Frames per second', '30')
+  .option('-t, --slide-time <n>', 'Seconds per slide', '3')
+  .option('-q, --quality <n>', 'Quality 1-100 (video only)', '80')
+  .action(async (dir, options) => {
+    try {
+      await exportPresentation(dir, {
+        output: options.output,
+        width: Number.parseInt(options.width, 10),
+        height: Number.parseInt(options.height, 10),
+        fps: Number.parseInt(options.fps, 10),
+        slideTime: Number.parseFloat(options.slideTime),
+        quality: Number.parseInt(options.quality, 10),
+      });
+    } catch (error) {
+      handleError(error);
+    }
+  });

package/src/cli/commands/init.ts

@@ -0,0 +1,125 @@
+/**
+ * Init Command
+ *
+ * Creates a new presentation deck with sample slides and configuration.
+ */
+
+import { Command } from 'commander';
+import { join } from 'node:path';
+import { handleError } from '../errors.js';
+
+export const initCommand = new Command('init')
+  .description('Create a new presentation deck')
+  .argument('<name>', 'Deck name (will create directory)')
+  .option('-t, --theme <name>', 'Theme to use', 'matrix')
+  .action(async (name, options) => {
+    try {
+      await initDeck(name, options.theme);
+      console.log(`Created deck: ${name}/`);
+      console.log('\nNext steps:');
+      console.log(`  cd ${name}/slides`);
+      console.log('  term-deck present .');
+    } catch (error) {
+      handleError(error);
+    }
+  });
+
+/**
+ * Initialize a new deck directory
+ *
+ * Creates the directory structure, configuration file, sample slides,
+ * and README for a new presentation deck.
+ */
+export async function initDeck(name: string, theme: string): Promise<void> {
+  const deckDir = join(process.cwd(), name);
+  const slidesDir = join(deckDir, 'slides');
+
+  // Create directories
+  await Bun.write(join(slidesDir, '.gitkeep'), '');
+
+  // Create deck.config.ts
+  const configContent = `import { defineConfig } from 'term-deck'
+import matrix from '@term-deck/theme-matrix'
+
+export default defineConfig({
+  title: '${name}',
+  theme: matrix,
+})
+`;
+  await Bun.write(join(slidesDir, 'deck.config.ts'), configContent);
+
+  // Create sample slides
+  const slide1 = `---
+title: ${name.toUpperCase()}
+bigText: ${name.toUpperCase()}
+gradient: fire
+---
+
+{GREEN}Welcome to your presentation{/}
+
+Press {CYAN}Space{/} or {CYAN}→{/} to advance
+`;
+
+  const slide2 = `---
+title: SLIDE TWO
+bigText: HELLO
+gradient: cool
+---
+
+{WHITE}This is the second slide{/}
+
+- Point one
+- Point two
+- Point three
+
+<!-- notes -->
+Remember to explain each point clearly.
+`;
+
+  const slide3 = `---
+title: THE END
+bigText: FIN
+gradient: pink
+---
+
+{ORANGE}Thank you!{/}
+
+Press {CYAN}q{/} to exit
+`;
+
+  await Bun.write(join(slidesDir, '01-intro.md'), slide1);
+  await Bun.write(join(slidesDir, '02-content.md'), slide2);
+  await Bun.write(join(slidesDir, '03-end.md'), slide3);
+
+  // Create README
+  const readme = `# ${name}
+
+A term-deck presentation.
+
+## Usage
+
+\`\`\`bash
+cd slides
+term-deck present .
+\`\`\`
+
+## Export
+
+\`\`\`bash
+term-deck export slides/ -o ${name}.mp4
+term-deck export slides/ -o ${name}.gif
+\`\`\`
+
+## Hotkeys
+
+| Key | Action |
+|-----|--------|
+| Space / → | Next slide |
+| ← | Previous slide |
+| 0-9 | Jump to slide |
+| l | Show slide list |
+| q | Quit |
+`;
+
+  await Bun.write(join(deckDir, 'README.md'), readme);
+}

package/src/cli/commands/present.ts

@@ -0,0 +1,29 @@
+/**
+ * Present Command
+ *
+ * Starts a presentation with the given options.
+ */
+
+import { Command } from 'commander';
+import { present } from '../../presenter/main.js';
+import { handleError } from '../errors.js';
+
+export const presentCommand = new Command('present')
+  .description('Start a presentation')
+  .argument('<dir>', 'Slides directory')
+  .option('-s, --start <n>', 'Start at slide number', '0')
+  .option('-n, --notes', 'Show presenter notes in separate terminal')
+  .option('--notes-tty <path>', 'TTY device for notes window (e.g., /dev/ttys001)')
+  .option('-l, --loop', 'Loop back to first slide after last')
+  .action(async (dir, options) => {
+    try {
+      await present(dir, {
+        startSlide: Number.parseInt(options.start, 10),
+        showNotes: options.notes,
+        notesTty: options.notesTty,
+        loop: options.loop,
+      });
+    } catch (error) {
+      handleError(error);
+    }
+  });