@thunderkiller/video-clipper 1.2.0 → 1.4.0

package/CHANGELOG.md

@@ -1,3 +1,22 @@
+# [1.4.0](https://github.com/AmreetKumarkhuntia/video-clipper/compare/v1.3.1...v1.4.0) (2026-03-20)
+
+### Features
+
+- **commitlint:** enforce conventional commit message format ([9d99882](https://github.com/AmreetKumarkhuntia/video-clipper/commit/9d998828617be72a81fbe4e72caa15eb28e88b82))
+
+## [1.3.1](https://github.com/AmreetKumarkhuntia/video-clipper/compare/v1.3.0...v1.3.1) (2026-03-20)
+
+### Bug Fixes
+
+- **release:** add @semantic-release/npm plugin to update package.json version ([fe6498d](https://github.com/AmreetKumarkhuntia/video-clipper/commit/fe6498d779459455387e2ca2736862e704ea8b1c))
+- **release:** add @semantic-release/npm to update package.json version ([9de3397](https://github.com/AmreetKumarkhuntia/video-clipper/commit/9de33977fe9f856aa8749436cbee7422dd622322))
+
+# [1.3.0](https://github.com/AmreetKumarkhuntia/video-clipper/compare/v1.2.0...v1.3.0) (2026-03-19)
+
+### Features
+
+- **npm:** configure npm package publishing ([b268345](https://github.com/AmreetKumarkhuntia/video-clipper/commit/b26834559ce97db683c393db765d7d5c7e989236))
+
 # [1.2.0](https://github.com/AmreetKumarkhuntia/video-clipper/compare/v1.1.1...v1.2.0) (2026-03-19)
 
 ### Features

package/CONTRIBUTING.md

@@ -0,0 +1,100 @@
+# Contributing
+
+## Getting Started
+
+```bash
+pnpm install
+```
+
+This will install all dependencies and set up git hooks via Husky.
+
+## Commit Message Format
+
+This project uses [Conventional Commits](https://www.conventionalcommits.org/) enforced by [commitlint](https://commitlint.js.org/).
+
+### Format
+
+```
+<type>(<scope>): <short description>
+
+- <detail 1>
+- <detail 2>
+```
+
+### Types
+
+| Type       | Description                                             | Version Bump           |
+| ---------- | ------------------------------------------------------- | ---------------------- |
+| `feat`     | New feature                                             | minor (1.0.0 -> 1.1.0) |
+| `fix`      | Bug fix                                                 | patch (1.0.0 -> 1.0.1) |
+| `docs`     | Documentation only                                      | none                   |
+| `refactor` | Code change that neither fixes a bug nor adds a feature | none                   |
+| `test`     | Adding or updating tests                                | none                   |
+| `chore`    | Maintenance tasks (deps, config, etc.)                  | none                   |
+| `style`    | Formatting, missing semicolons, etc. (no code change)   | none                   |
+| `perf`     | Performance improvement                                 | none                   |
+| `ci`       | CI/CD configuration changes                             | none                   |
+| `build`    | Build system or external dependency changes             | none                   |
+| `revert`   | Reverts a previous commit                               | none                   |
+
+### Rules
+
+- **type** (required): one from the table above
+- **scope** (recommended): kebab-case name of the feature area, e.g. `release`, `transcript-fetcher`, `llm-analyzer`
+- **short description** (required): lowercase, imperative mood, max 100 chars, no period at end
+- **body** (optional): pointwise with `-`, max 500 chars total
+
+### Examples
+
+```
+feat(clip-refiner): add overlap detection for adjacent segments
+
+- detect when refined segments overlap by more than 2s
+- merge overlapping segments and keep the higher-scored one
+```
+
+```
+fix(release): add @semantic-release/npm to update package.json version
+
+- add @semantic-release/npm with npmPublish: false
+- npm publish remains a separate workflow step
+```
+
+```
+docs(readme): add advanced examples section
+```
+
+### Breaking Changes
+
+Add `BREAKING CHANGE:` in the commit body or `!` after the type to trigger a major version bump:
+
+```
+feat(config)!: rename ENV_VAR to NEW_ENV_VAR
+
+BREAKING CHANGE: ENV_VAR is no longer supported, use NEW_ENV_VAR instead
+```
+
+## Git Hooks
+
+The following hooks run automatically on every commit:
+
+| Hook         | What it runs                                                  |
+| ------------ | ------------------------------------------------------------- |
+| `pre-commit` | `lint-staged` (Prettier), `type-check` (tsc), `test` (vitest) |
+| `commit-msg` | `commitlint` (validates commit message format)                |
+
+If your commit is rejected, check the error output — it will tell you exactly which rule was violated.
+
+## Code Style
+
+- TypeScript only — no plain `.js` files
+- Prettier handles formatting automatically via `lint-staged`
+- Run `pnpm format` to format all files manually
+- Run `pnpm type-check` to check for type errors
+
+## Testing
+
+- Write unit tests for pure functions
+- Test files live in `tests/` at the project root
+- Run `pnpm test` to run all tests
+- Run `pnpm test:watch` for watch mode

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2025, @thunderkiller/video-clipper
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/commitlint.config.js

@@ -0,0 +1,25 @@
+export default {
+  extends: ['@commitlint/config-conventional'],
+  rules: {
+    'type-enum': [
+      2,
+      'always',
+      [
+        'feat',
+        'fix',
+        'docs',
+        'refactor',
+        'test',
+        'chore',
+        'style',
+        'perf',
+        'ci',
+        'build',
+        'revert',
+      ],
+    ],
+    'scope-case': [2, 'always', 'kebab-case'],
+    'subject-max-length': [2, 'always', 100],
+    'body-max-line-length': [2, 'always', 500],
+  },
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thunderkiller/video-clipper",
-  "version": "1.2.0",
+  "version": "1.4.0",
   "description": "CLI that analyzes YouTube transcripts with an LLM to find interesting moments and cut clips",
   "license": "ISC",
   "author": "",
@@ -49,6 +49,8 @@
     "zod": "^4.3.6"
   },
   "devDependencies": {
+    "@commitlint/cli": "^20.5.0",
+    "@commitlint/config-conventional": "^20.5.0",
     "@semantic-release/changelog": "^6.0.3",
     "@semantic-release/git": "^10.0.1",
     "@semantic-release/github": "^12.0.6",

package/.github/workflows/ci.yml

@@ -1,42 +0,0 @@
-name: CI
-
-on:
-  push:
-    branches:
-      - main
-      - master
-  pull_request:
-    branches:
-      - main
-      - master
-jobs:
-  ci:
-    name: Type-check, Format, Test & Build
-    runs-on: ubuntu-latest
-
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-
-      - name: Setup Node.js (LTS)
-        uses: actions/setup-node@v4
-        with:
-          node-version: '24'
-
-      - name: Setup pnpm
-        uses: pnpm/action-setup@v4
-
-      - name: Install dependencies
-        run: pnpm install --frozen-lockfile
-
-      - name: Type-check
-        run: pnpm type-check
-
-      - name: Format check
-        run: pnpm format:check
-
-      - name: Test
-        run: pnpm test
-
-      - name: Build
-        run: pnpm build

package/.github/workflows/release.yml

@@ -1,76 +0,0 @@
-name: Release
-
-on:
-  push:
-    branches:
-      - master
-
-jobs:
-  release:
-    name: Semantic Release
-    runs-on: ubuntu-latest
-    permissions:
-      contents: write
-      id-token: write
-
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-          persist-credentials: false
-
-      - name: Setup pnpm
-        uses: pnpm/action-setup@v4
-
-      - name: Setup Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: '24'
-          registry-url: 'https://registry.npmjs.org'
-
-      - name: Setup npm auth
-        run: echo "//registry.npmjs.org/:_authToken=\${{ secrets.NPM_TOKEN }}" > ~/.npmrc
-
-      - name: Install dependencies
-        run: pnpm install --frozen-lockfile
-
-      - name: Build
-        run: pnpm build
-
-      - name: Configure Git
-        run: |
-          git config user.name "github-actions[bot]"
-          git config user.email "github-actions[bot]@users.noreply.github.com"
-          git remote set-url origin https://x-access-token:${{ secrets.PUSH_TOKEN }}@github.com/${{ github.repository }}.git
-
-      - name: Stage 1 GitHub Release (versioning, tags, releases)
-        id: github_release
-        run: npx semantic-release
-        env:
-          GITHUB_TOKEN: ${{ secrets.PUSH_TOKEN }}
-
-      - name: Pull updated package.json after semantic-release
-        if: success()
-        run: git pull origin master
-
-      - name: Verify GitHub Release
-        if: success()
-        run: |
-          echo "Checking for new git tags..."
-          CURRENT_TAG=$(git describe --tags --abbrev=0 2>/dev/null || echo "none")
-          echo "Current tag: $CURRENT_TAG"
-
-          if [ "$CURRENT_TAG" != "none" ]; then
-            echo "✅ New tag created: $CURRENT_TAG"
-            echo "Proceeding to npm publish..."
-          else
-            echo "❌ No new tag created - skipping npm publish"
-            exit 1
-          fi
-
-      - name: Stage 2 Publish to NPM
-        if: success()
-        run: npm publish
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/.husky/pre-commit

@@ -1,3 +0,0 @@
-pnpm lint-staged
-pnpm type-check
-pnpm test

package/.prettierignore

@@ -1,6 +0,0 @@
-dist/
-node_modules/
-downloads/
-outputs/
-pnpm-lock.yaml
-package-lock.json

package/.prettierrc

@@ -1,7 +0,0 @@
-{
-  "singleQuote": true,
-  "semi": true,
-  "tabWidth": 2,
-  "trailingComma": "all",
-  "printWidth": 100
-}

package/.releaserc.json

@@ -1,21 +0,0 @@
-{
-  "branches": ["master"],
-  "plugins": [
-    "@semantic-release/commit-analyzer",
-    "@semantic-release/release-notes-generator",
-    [
-      "@semantic-release/changelog",
-      {
-        "changelogFile": "CHANGELOG.md"
-      }
-    ],
-    [
-      "@semantic-release/git",
-      {
-        "assets": ["package.json", "CHANGELOG.md"],
-        "message": "chore(release): ${nextRelease.version} [skip ci]"
-      }
-    ],
-    "@semantic-release/github"
-  ]
-}

package/AGENTS.md

@@ -1,122 +0,0 @@
-# Agent Instructions
-
-## Project
-
-TypeScript CLI that analyzes YouTube transcripts with an LLM to find interesting moments and optionally cut video clips.
-
-See `docs/plan.md` for the full architecture.
-
-## Stack
-
-- TypeScript (Node.js 18+)
-- Vercel AI SDK (`ai`, `@ai-sdk/openai`, `@ai-sdk/anthropic`, `@ai-sdk/google`, `@ai-sdk/xai`, `@ai-sdk/mistral`, `@ai-sdk/groq`) with `generateObject` + `zod` for structured LLM output
-- Multi-provider support: OpenAI, Anthropic, Google, XAI, Mistral, Groq, Zai, OpenRouter
-- `youtube-transcript` for transcript fetching
-- `yt-dlp` + `execa` for video download
-- `fluent-ffmpeg` for clip cutting
-- `zod` for config validation at startup
-- `p-limit` for concurrency control
-
-## Project Structure
-
-```
-src/
-  config/          # zod-validated env config — import this, never read process.env directly
-    index.ts
-    env.ts
-  services/        # core pipeline modules
-    urlParser/
-    metadataExtractor/
-    transcriptFetcher/
-    chunkBuilder/
-    llmAnalyzer/
-    segmentRanker/
-    clipRefiner/
-    videoDownloader/
-    clipGenerator/
-  types/           # shared TypeScript types
-    index.ts
-    config.ts
-    segment.ts
-    transcript.ts
-    video.ts
-    youtube-transcript.d.ts
-  utils/           # utility functions
-    cache.ts        # transcript + chunk LLM result caching
-    dumper.ts       # transcript/analysis JSON dumps
-    redactConfig.ts # config formatting for logs (redacts API keys)
-    format.ts       # timestamp formatting utilities
-    logger.ts       # logging utilities
-    modelFactory.ts # LLM provider factory
-  index.ts         # CLI entrypoint
-tests/             # all unit tests (mirrors module names)
-  urlParser.test.ts
-  chunkBuilder.test.ts
-  segmentRanker.test.ts
-downloads/         # yt-dlp output (gitignored)
-outputs/           # ffmpeg clip output, caches, dumps (gitignored)
-  cache/           # transcript + LLM result cache
-  transcript/       # transcript dumps
-  analysis/        # analysis dumps
-docs/
-  plan.md
-  free-models.md
-```
-
-## Code Rules
-
-- All code in TypeScript — no plain `.js` files
-- Every function must have explicit input/output types; avoid `any`
-- Use `zod` for all external data validation (LLM output, env vars, API responses)
-- Never read `process.env` directly — always import from `src/config.ts`
-- Never hardcode API keys, model names, thresholds, or directory paths — all come from config
-- Use `async/await` — no raw `.then()` chains
-- Use `Promise.allSettled` for parallel LLM calls so one failure doesn't abort the rest
-- Handle errors explicitly — no silent catches. Log a warning with the chunk index and reason on skip.
-
-## LLM Usage
-
-- Use `generateObject` (not `generateText`) for all LLM calls that return structured data
-- Define a `zod` schema for every LLM response before writing the prompt
-- Keep prompts in the same file as the function that uses them
-- Do not retry on malformed JSON — `generateObject` handles structured output natively
-- On any LLM call failure, catch and log, then continue — never crash the pipeline
-
-## Module Conventions
-
-Each module in `src/modules/` should:
-
-- Export a single main function named after the module (e.g. `fetchTranscript`, `buildChunks`)
-- Accept typed inputs and return typed outputs (no `any`)
-- Not import from other modules except `config.ts` and `types.ts` unless there is a clear dependency
-
-## Transcript Notes
-
-- `youtube-transcript` returns `offset` in **milliseconds** — normalize to seconds immediately after fetching
-- Micro-blocks group raw lines into ~15s windows before chunking
-- LLM chunks are 120s windows with 20s overlap — built from micro-blocks, not raw lines
-
-## Naming
-
-- Files: `camelCase.ts`
-- Functions: `camelCase`
-- Types/interfaces: `PascalCase`
-- Constants: `UPPER_SNAKE_CASE`
-- Zod schemas: `PascalCase` + `Schema` suffix (e.g. `SegmentSchema`)
-
-## Testing
-
-- Write unit tests for pure functions (URL parser, chunker, ranker, deduplicator)
-- Do not unit test functions that call external services (LLM, yt-dlp, ffmpeg) — integration test those separately
-- Test files live in `tests/` at the project root, mirroring the module name (e.g. `tests/urlParser.test.ts`)
-
-## Git
-
-- Commit messages: lowercase, imperative
-- One logical change per commit
-- Never commit `.env`, `downloads/`, or `outputs/`
-- It should be pointwise `-`
-- Shouldn't be more than 500 characters all together
-- it should be categorized as feat: , fix:, docs:, refactor etc...
-- also it should include specifics like feat(<feature>)
-- so final structure is <change ex: feat, docs, fix>: <short desc> followed by <full desc> pointwise

package/docs/free-models.md

@@ -1,78 +0,0 @@
-# Free Models via OpenRouter
-
-This project supports [OpenRouter](https://openrouter.ai) as an LLM provider, which gives access to a number of completely free models (no cost per token).
-
-## Setup
-
-```env
-LLM_PROVIDER=openrouter
-OPENROUTER_API_KEY=sk-or-...
-LLM_MODEL=<model-id-from-table-below>
-```
-
----
-
-## Recommended Free Models for Transcript Analysis
-
-These models have sufficient context length and instruction-following capability to work well with `generateObject` and structured transcript analysis.
-
-| Model ID                                        | Name                              | Context |
-| ----------------------------------------------- | --------------------------------- | ------- |
-| `meta-llama/llama-3.3-70b-instruct:free`        | Meta: Llama 3.3 70B Instruct      | 128K    |
-| `google/gemma-3-27b-it:free`                    | Google: Gemma 3 27B               | 131K    |
-| `mistralai/mistral-small-3.1-24b-instruct:free` | Mistral: Mistral Small 3.1 24B    | 128K    |
-| `nousresearch/hermes-3-llama-3.1-405b:free`     | Nous: Hermes 3 405B Instruct      | 131K    |
-| `qwen/qwen3-next-80b-a3b-instruct:free`         | Qwen: Qwen3 Next 80B A3B Instruct | 262K    |
-
-**Recommended default:** `meta-llama/llama-3.3-70b-instruct:free`
-
-- Most battle-tested for structured JSON output
-- Reliable with `generateObject` (which requires strict schema adherence)
-- 128K context handles most YouTube transcripts comfortably
-
----
-
-## All Available Free Models (as of March 2026)
-
-| Model ID                                                        | Name                              | Context   |
-| --------------------------------------------------------------- | --------------------------------- | --------- |
-| `openrouter/hunter-alpha`                                       | Hunter Alpha                      | 1,048,576 |
-| `openrouter/healer-alpha`                                       | Healer Alpha                      | 262,144   |
-| `nvidia/nemotron-3-super-120b-a12b:free`                        | NVIDIA: Nemotron 3 Super          | 262,144   |
-| `minimax/minimax-m2.5:free`                                     | MiniMax: MiniMax M2.5             | 196,608   |
-| `openrouter/free`                                               | Free Models Router                | 200,000   |
-| `stepfun/step-3.5-flash:free`                                   | StepFun: Step 3.5 Flash           | 256,000   |
-| `arcee-ai/trinity-large-preview:free`                           | Arcee AI: Trinity Large Preview   | 131,000   |
-| `liquid/lfm-2.5-1.2b-thinking:free`                             | LiquidAI: LFM2.5-1.2B-Thinking    | 32,768    |
-| `liquid/lfm-2.5-1.2b-instruct:free`                             | LiquidAI: LFM2.5-1.2B-Instruct    | 32,768    |
-| `nvidia/nemotron-3-nano-30b-a3b:free`                           | NVIDIA: Nemotron 3 Nano 30B A3B   | 256,000   |
-| `arcee-ai/trinity-mini:free`                                    | Arcee AI: Trinity Mini            | 131,072   |
-| `nvidia/nemotron-nano-12b-v2-vl:free`                           | NVIDIA: Nemotron Nano 12B 2 VL    | 128,000   |
-| `qwen/qwen3-next-80b-a3b-instruct:free`                         | Qwen: Qwen3 Next 80B A3B Instruct | 262,144   |
-| `nvidia/nemotron-nano-9b-v2:free`                               | NVIDIA: Nemotron Nano 9B V2       | 128,000   |
-| `openai/gpt-oss-120b:free`                                      | OpenAI: gpt-oss-120b              | 131,072   |
-| `openai/gpt-oss-20b:free`                                       | OpenAI: gpt-oss-20b               | 131,072   |
-| `z-ai/glm-4.5-air:free`                                         | Z.ai: GLM 4.5 Air                 | 131,072   |
-| `qwen/qwen3-coder:free`                                         | Qwen: Qwen3 Coder 480B A35B       | 262,000   |
-| `cognitivecomputations/dolphin-mistral-24b-venice-edition:free` | Venice: Uncensored                | 32,768    |
-| `google/gemma-3n-e2b-it:free`                                   | Google: Gemma 3n 2B               | 8,192     |
-| `google/gemma-3n-e4b-it:free`                                   | Google: Gemma 3n 4B               | 8,192     |
-| `qwen/qwen3-4b:free`                                            | Qwen: Qwen3 4B                    | 40,960    |
-| `mistralai/mistral-small-3.1-24b-instruct:free`                 | Mistral: Mistral Small 3.1 24B    | 128,000   |
-| `google/gemma-3-4b-it:free`                                     | Google: Gemma 3 4B                | 32,768    |
-| `google/gemma-3-12b-it:free`                                    | Google: Gemma 3 12B               | 32,768    |
-| `google/gemma-3-27b-it:free`                                    | Google: Gemma 3 27B               | 131,072   |
-| `meta-llama/llama-3.3-70b-instruct:free`                        | Meta: Llama 3.3 70B Instruct      | 128,000   |
-| `meta-llama/llama-3.2-3b-instruct:free`                         | Meta: Llama 3.2 3B Instruct       | 131,072   |
-| `nousresearch/hermes-3-llama-3.1-405b:free`                     | Nous: Hermes 3 405B Instruct      | 131,072   |
-
-> Free models may have rate limits or availability constraints. Check [openrouter.ai/models](https://openrouter.ai/models) for the latest list.
-
----
-
-## Notes
-
-- Free models on OpenRouter are subject to rate limits (typically lower than paid tiers).
-- Avoid models with context < 32K for long videos — chunks may not fit.
-- Models marked `:free` are permanently free; others (like `openrouter/hunter-alpha`) may change pricing.
-- If `generateObject` fails with a free model, it usually means the model doesn't follow JSON schema strictly enough — switch to `meta-llama/llama-3.3-70b-instruct:free` as a fallback.