Skip to content

AGENTS.md

Latest commit

 

History

History
65 lines (51 loc) · 3.14 KB

AGENTS.md

File metadata and controls

65 lines (51 loc) · 3.14 KB
Raw

AGENTS.md

This file provides guidance to WARP (warp.dev) when working with code in this repository.

Project Overview

A CLI tool to migrate videos from Vimeo to Bunny.net Stream. Videos transfer directly from Vimeo to Bunny via URL fetch (no local downloads). The tool preserves folder structure (Vimeo folders → Bunny collections) and metadata (title, description, tags).

Build & Development Commands

npm install           # Install dependencies
npm run build         # Compile TypeScript to dist/
npm run dev           # Run directly with ts-node (development)
npm run start         # Run compiled version from dist/
npm run build:binaries  # Create standalone binaries with pkg

Running the CLI During Development

# Via ts-node
npx ts-node src/index.ts <command>

# Or after building
node dist/index.js <command>

# Or if globally linked
vimeo2bunny <command>

Architecture

Entry Point & Command Structure

  • src/index.ts - CLI entry point using Commander.js. Defines commands: config, config:reset, list, migrate, status
  • src/commands/ - Individual command implementations (config.ts, list.ts, migrate.ts, status.ts)

Service Layer

  • src/services/vimeo.ts - VimeoClient class wrapping Vimeo API. Handles pagination, rate limiting with exponential backoff, video/folder listing
  • src/services/bunny.ts - BunnyClient class wrapping Bunny Stream API. Handles collections, video fetch via URL, processing status polling
  • src/services/migration.ts - MigrationService orchestrates the migration in phases:
    1. Discover Vimeo content
    2. Create Bunny collections from folders
    3. Initialize video migration tracking
    4. Migrate videos with concurrency control and timeout handling

Type Definitions

  • src/types/index.ts - All TypeScript interfaces: Vimeo types (VimeoVideo, VimeoFolder, etc.), Bunny types (BunnyVideo, BunnyCollection, etc.), migration state types

Utilities

  • src/utils/config.ts - Credential storage using OS keychain (via keytar) with conf fallback. Migration state persistence to ~/.vimeo2bunny/migration-state.json
  • src/utils/keychain.ts - Secure credential storage abstraction (macOS Keychain, Windows Credential Store, Linux Secret Service)
  • src/utils/security.ts - Input validation (URL, IDs), metadata sanitization, safe error messages
  • src/utils/schemas.ts - Zod schemas for validating migration state
  • src/utils/logger.ts - Colored console output with chalk
  • src/utils/progress.ts - Spinner/progress indicators with ora

Key Design Patterns

  • Videos are tracked by vimeoId metatag in Bunny to detect already-migrated videos and enable resumable migrations
  • Rate limiting handled via axios interceptors with retry-after header support
  • Migration state is persisted after each operation for crash recovery
  • Both APIs use pagination - always fetch all pages when listing

Configuration Priority

Credentials are resolved in order: Environment variables (VIMEO_ACCESS_TOKEN, BUNNY_LIBRARY_ID, BUNNY_LIBRARY_API_KEY) > OS keychain > conf file

Testing Notes

No test framework is configured. When adding tests, verify the project's preferred testing approach first.