yt-dlp-bridge 0.1.5 → 0.2.0

package/README.md

@@ -1,313 +1,332 @@
 # yt-dlp-bridge
 
-[![npm version](https://img.shields.io/npm/v/yt-dlp-bridge.svg)](https://www.npmjs.com/package/yt-dlp-bridge)
-[![npm downloads](https://img.shields.io/npm/dm/yt-dlp-bridge.svg)](https://www.npmjs.com/package/yt-dlp-bridge)
-[![CI](https://github.com/antonio-orionus/yt-dlp-bridge/actions/workflows/ci.yml/badge.svg)](https://github.com/antonio-orionus/yt-dlp-bridge/actions/workflows/ci.yml)
+[![registry version](https://img.shields.io/npm/v/yt-dlp-bridge.svg)](https://www.npmjs.com/package/yt-dlp-bridge)
+[![registry downloads](https://img.shields.io/npm/dm/yt-dlp-bridge.svg)](https://www.npmjs.com/package/yt-dlp-bridge)
+[![CI](https://github.com/antonio-orionus/Arroxy/actions/workflows/ci.yml/badge.svg)](https://github.com/antonio-orionus/Arroxy/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
-[![TypeScript](https://img.shields.io/badge/TypeScript-007ACC?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
-[![Node.js >=22.13](https://img.shields.io/badge/node-%3E%3D22.13-brightgreen.svg)](package.json)
 
-TypeScript primitives for building safe, policy-aware integrations on top of `yt-dlp`: command planning, argv generation, environment checks, process execution, output parsing, redaction, and structured errors.
+TypeScript library for safe, no-shell `yt-dlp` integration in Node.js services: workflow planning, argv generation, command facts, environment checks, process execution, output parsing, secret redaction, filesystem policy, and structured errors.
 
-`yt-dlp-bridge` is intentionally MCP-agnostic. It is the integration layer used by `yt-dlp-mcp-server`, but it can be used anywhere a Node.js service needs to plan or run `yt-dlp` without shell interpolation.
+`yt-dlp-bridge` is intentionally app-agnostic. It is used by Arroxy and `yt-dlp-mcp-server`, but it does not own Electron token minting, binary resolution, retries, queue lifecycle, settings stores, plugin installation, or UI progress policy.
 
-## Contents
+Source and contributions live in the Arroxy monorepo at [`packages/yt-dlp-bridge`](https://github.com/antonio-orionus/Arroxy/tree/main/packages/yt-dlp-bridge).
 
+- [Install](#install)
 - [Features](#features)
-- [Quick Start](#quick-start)
-- [Installation](#installation)
+- [What changed in 0.2.0](#what-changed-in-020)
 - [Usage](#usage)
-- [API Surface](#api-surface)
+- [API](#api)
 - [Configuration](#configuration)
 - [Requirements](#requirements)
 - [Development](#development)
-- [Release](#release)
 - [Troubleshooting](#troubleshooting)
 - [License](#license)
 
-## Features
-
-- Source-derived option catalog generated from `yt_dlp.options.create_parser`.
-- Safe argv builders that return argument arrays instead of shell command strings.
-- Dependency-aware download and post-processing plans for `yt-dlp`, `ffmpeg`, `ffprobe`, external downloaders, browser impersonation, and JavaScript runtimes.
-- Managed output policy for output roots, temp roots, archive files, overwrite behavior, and parent-directory traversal checks.
-- Secret redaction for auth flags, cookies, signed URLs, and command previews.
-- Parsers for JSON lines, format lists, subtitle lists, thumbnail lists, progress output, and final output paths.
-- Structured error adaptation through [`ytdlp-errors`](https://www.npmjs.com/package/ytdlp-errors).
-- ESM and TypeScript declarations out of the box.
-
-## Quick Start
+## Install
 
 ```bash
-npm install yt-dlp-bridge
+bun add yt-dlp-bridge
 # pnpm add yt-dlp-bridge
 # yarn add yt-dlp-bridge
-# bun add yt-dlp-bridge
 ```
 
-```ts
-import {
-  PlanDownloadInputSchema,
-  loadConfig,
-  planDownload
-} from "yt-dlp-bridge";
-
-const config = loadConfig();
-const input = PlanDownloadInputSchema.parse({
-  url: "https://www.youtube.com/watch?v=BaW_jenozKc",
-  kind: "audio",
-  postprocess: {
-    audioFormat: "mp3"
-  },
-  output: {
-    outputRoot: "audio"
-  }
-});
+Requires Node.js >= 22.13 and ESM.
 
-const plan = await planDownload(input, config);
+## Features
 
-console.log(plan.commandPreview.command);
-console.log(plan.commandPreview.redactedArgs);
-console.log(plan.requiredDependencies);
-```
+- One canonical `planWorkflow(input, options?)` planner with caller-owned app inputs and managed/server schema inputs.
+- Caller-owned probe/media/subtitle inputs for apps that already resolved output directories, format selection, subtitles, embeds, resume info JSON, and audio conversion policy.
+- Managed schema inputs for inspect, media, audio, subtitles, thumbnail, playlist, postprocess, and expert/raw workflows that need bridge-owned normalization.
+- Workflow facts for media-vs-sidecar behavior, output roots/templates, playlist sentinel scope, subtitle format, dependencies, risks, and side effects.
+- Safe argv arrays instead of shell command strings.
+- Managed output policy for output roots, temp roots, archive files, overwrite behavior, and parent-directory traversal checks.
+- Secret redaction for auth flags, cookies, PO tokens, visitor data, proxies, signed URLs, and command previews.
+- Parsers for JSON lines, format lists, subtitle lists, thumbnail lists, progress output, final output paths, and live yt-dlp output events.
+- Low-level process runner using `spawn` with `shell: false`, bounded output capture, timeouts, and structured failures.
+- Source-derived option catalog generated from `yt_dlp.options.create_parser`.
+- ESM and TypeScript declarations.
 
-## Installation
+## What changed in 0.2.0
 
-For package consumers:
+`0.2.0` keeps `planWorkflow` as the single planner, but separates the public input surface into two paths:
 
-```bash
-npm install yt-dlp-bridge
-```
+- Use caller-owned inputs (`ProbeWorkflowInput`, `CallerMediaWorkflowInput`, `CallerSubtitlesWorkflowInput`) when your app owns job state, output folders, format selectors, subtitle mode, resume metadata, and user-facing workflow policy.
+- Use managed Zod schemas (`WorkflowDownloadInputSchema`, `WorkflowInspectInputSchema`, `WorkflowPostprocessInputSchema`, `WorkflowExpertInputSchema`) when a server integration wants the bridge to normalize config, auth, network, output roots, and yt-dlp workflow options from request-like input.
 
-For source development, this repository uses pnpm:
+Migration notes for `0.1.x` consumers:
 
-```bash
-git clone https://github.com/antonio-orionus/yt-dlp-bridge.git
-cd yt-dlp-bridge
-pnpm install
-pnpm run build
-pnpm test
-```
+- If you used managed download schemas only to plan app-owned downloads, map your app job to `CallerMediaWorkflowInput` or `CallerSubtitlesWorkflowInput` instead.
+- `WorkflowInputSchema` validates the managed/server schema family. Caller-owned app inputs are TypeScript interfaces, so validate local job state before mapping it into the bridge.
+- Media planning now includes app-oriented resume hardening, including `--continue`, chunk sizing, temp info JSON output, and `resume.loadInfoJsonPath` planning that omits the original URL.
+- Embedded subtitle planning forces the safe MKV merge container and suppresses thumbnail embedding when needed for subtitle muxing.
+- App runtime decisions still stay outside the package: binary selection, token minting, retries, queue lifecycle, cancellation UI, progress display, and settings persistence remain caller-owned.
 
 ## Usage
 
-### Build Inspect Arguments
+Choose the input style based on ownership. App integrations should usually start with caller-owned inputs. MCP/server-style integrations should usually start with managed schemas.
 
-Use the Zod schemas to fill defaults before passing inputs into the low-level builders.
+### Plan from a caller-owned app adapter
 
-```ts
-import { InspectInputSchema, buildMetadataArgs } from "yt-dlp-bridge";
+App adapters should map local state into `WorkflowInput`, then keep app-owned orchestration outside the bridge.
 
-const input = InspectInputSchema.parse({
-  url: "https://www.youtube.com/watch?v=BaW_jenozKc"
-});
+```ts
+import { planWorkflow, type CallerMediaWorkflowInput } from "yt-dlp-bridge";
+
+function toWorkflowInput(job: PreparedJob): CallerMediaWorkflowInput {
+  return {
+    kind: "media",
+    url: job.url,
+    output: { directory: job.outputDir, tempDirectory: job.tempDir },
+    selection: {
+      formatSelector: job.formatSelector,
+      mergeOutputFormat: job.mergeOutputFormat
+    },
+    subtitles: job.embedSubtitles
+      ? { embed: true, languages: job.subtitleLanguages, writeAuto: job.writeAutoSubtitles }
+      : undefined,
+    embed: {
+      metadata: job.embedMetadata,
+      thumbnail: job.embedThumbnail,
+      chapters: job.embedChapters
+    },
+    resume: job.infoJsonPath ? { loadInfoJsonPath: job.infoJsonPath } : undefined
+  };
+}
 
-const args = buildMetadataArgs(input);
+const plan = planWorkflow(toWorkflowInput(job));
 
-console.log(args);
-// ["--ignore-config", "--no-warnings", "--dump-json", "https://www.youtube.com/watch?v=BaW_jenozKc"]
+console.log(plan.args);
+console.log(plan.facts.sideEffects);
 ```
 
-### Plan a Download
+The bridge owns yt-dlp semantics such as audio conversion arguments, subtitle/embed container rules, playlist sentinel logic, dependency reasons, risk/side-effect facts, output path facts, resume argv, and redaction. The adapter owns local job models, runtime selection, retries, token minting, cancellation, progress policy, and user-facing status.
+
+### Plan a managed workflow
 
-`planDownload` resolves output policy, builds the final argv, redacts secrets, checks available dependencies, and explains risks and side effects before anything is downloaded.
+Use managed schemas when a consumer accepts request-like input and wants the bridge to normalize defaults before planning a stable `yt-dlp` argv plus facts.
 
 ```ts
-import {
-  PlanDownloadInputSchema,
-  loadConfig,
-  planDownload
-} from "yt-dlp-bridge";
+import { WorkflowDownloadInputSchema, planWorkflow } from "yt-dlp-bridge";
+import { loadConfig } from "yt-dlp-bridge/config";
 
 const config = loadConfig({
   YTDLP_MCP_OUTPUT_ROOT: "/srv/downloads",
   YTDLP_MCP_TEMP_ROOT: "/srv/downloads/.tmp"
 });
 
-const input = PlanDownloadInputSchema.parse({
+const input = WorkflowDownloadInputSchema.parse({
+  kind: "audio",
   url: "https://www.youtube.com/watch?v=BaW_jenozKc",
-  kind: "video",
+  postprocess: { audioFormat: "mp3" },
+  output: { outputTemplate: "%(title).180B [%(id)s].%(ext)s" }
+});
+
+const plan = planWorkflow(input, {
+  config,
+  configFiles: { mode: "disabled" },
+  plugins: { mode: "native" }
+});
+
+console.log(plan.args);
+console.log(plan.redactedArgs);
+console.log(plan.facts.dependencies.required);
+```
+
+Managed schemas are the runtime-validation layer for this path:
+
+```ts
+import { WorkflowInputSchema } from "yt-dlp-bridge";
+
+const input = WorkflowInputSchema.parse(request.body);
+const plan = planWorkflow(input, { config });
+```
+
+`WorkflowPlan` has this shape:
+
+```ts
+{
+  kind: "probe" | "inspect" | "media" | "audio" | "subtitles" | "thumbnail" | "playlist" | "postprocess" | "expert",
+  args: string[],
+  redactedArgs: string[],
+  facts: {
+    isMediaDownload: boolean,
+    output?: {
+      directory?: string,
+      tempDirectory?: string,
+      outputRoot?: string,
+      tempRoot?: string,
+      template?: string,
+      allowOverwrite?: boolean
+    },
+    playlistScope?: {
+      requestedCount: number,
+      sentinel: boolean,
+      ytDlpFlag: "--playlist-end" | "--playlist-items",
+      ytDlpValue: string
+    },
+    effectiveSubtitleFormat?: "srt" | "vtt" | "ass",
+    dependencies: { required: unknown[], optional: unknown[] },
+    risks: string[],
+    sideEffects: string[]
+  }
+}
+```
+
+### Probe playlists
+
+Probe planning owns playlist mode and sentinel range behavior.
+
+```ts
+import { planWorkflow } from "yt-dlp-bridge";
+
+const probe = planWorkflow({
+  kind: "probe",
+  url: "https://www.youtube.com/playlist?list=...",
   selection: {
-    downloadArchive: "archive.txt"
-  },
-  format: {
-    format: "bv*+ba/b"
-  },
-  output: {
-    outputTemplate: "%(playlist_index)s-%(title).180B [%(id)s].%(ext)s"
+    playlistMode: "playlist",
+    playlistScope: { items: { kind: "first", count: 50 } }
   }
 });
 
-const plan = await planDownload(input, config);
+console.log(probe.args);
+console.log(probe.facts.playlistScope);
+```
+
+### Parse live yt-dlp output
+
+Use `parseYtDlpOutputLine` to turn noisy output into stable events. App-specific adapters can map these events to progress bars, queue resume evidence, logs, or MCP notifications.
+
+```ts
+import { parseYtDlpOutputLine } from "yt-dlp-bridge/parsers";
+
+const event = parseYtDlpOutputLine('[Merger] Merging formats into "/tmp/video.mp4"');
 
-console.log(plan.argv);
-console.log(plan.risks);
-console.log(plan.sideEffects);
+if (event?.kind === "merge") {
+  console.log(event.path);
+}
 ```
 
-### Run a Planned Command
+### Run a planned command
 
-The runner uses `spawn` with `shell: false`, bounded output capture, timeouts, and structured failures.
+The bridge runner is low-level. It executes a command path plus argv; it does not resolve binaries or decide retries.
 
 ```ts
-import {
-  PlanDownloadInputSchema,
-  loadConfig,
-  planDownload,
-  runCommand,
-  toStructuredError
-} from "yt-dlp-bridge";
-
-const config = loadConfig();
-const input = PlanDownloadInputSchema.parse({
-  url: "https://www.youtube.com/watch?v=BaW_jenozKc",
-  kind: "video"
-});
+import { planWorkflow } from "yt-dlp-bridge";
+import { runCommand } from "yt-dlp-bridge/runner";
+import { toStructuredError } from "yt-dlp-bridge/errors";
 
-const plan = await planDownload(input, config);
+const plan = planWorkflow({
+  kind: "media",
+  url: "https://www.youtube.com/watch?v=BaW_jenozKc"
+});
 
 try {
-  const result = await runCommand(plan.commandPreview.command, plan.commandPreview.args, {
-    timeoutMs: config.defaultTimeoutMs,
-    maxOutputBytes: config.maxOutputBytes
+  const result = await runCommand("yt-dlp", plan.args, {
+    timeoutMs: 900_000,
+    maxOutputBytes: 4 * 1024 * 1024
   });
-
   console.log(result.stdout);
 } catch (error) {
   console.error(toStructuredError(error));
 }
 ```
 
-### Inspect the Option Catalog
+### Query the option catalog
 
-The bundled catalog in this release is generated from `yt_dlp.options.create_parser` for yt-dlp `2026.03.17` and contains 323 upstream options.
+The bundled catalog is generated from `yt_dlp.options.create_parser` for yt-dlp `2026.03.17` and contains 323 upstream options.
 
 ```ts
-import {
-  UPSTREAM_OPTION_CATALOG,
-  findOptionByFlag,
-  listLongFlags,
-  optionMetadata
-} from "yt-dlp-bridge";
+import { UPSTREAM_OPTION_CATALOG, findOptionByFlag, listLongFlags, optionMetadata } from "yt-dlp-bridge/option-catalog";
 
 const format = findOptionByFlag("--format");
-
 console.log(UPSTREAM_OPTION_CATALOG.optionCount);
 console.log(listLongFlags().includes("--dump-json"));
 console.log(format ? optionMetadata(format) : undefined);
 ```
 
-## API Surface
+## API
+
+Prefer the root export for workflow planning and subpaths for lower-level utilities.
 
 | Area | Exports |
 | --- | --- |
-| Argv builders | `ytdlpCommand`, `buildMetadataArgs`, `buildSingleJsonArgs`, `buildListArgs`, `buildSimulationArgs`, `buildDownloadArgs` |
-| Planning | `planDownload`, `planPostprocess` |
-| Configuration and environment | `loadConfig`, `CONFIG`, `checkEnvironment` |
-| Filesystem policy | `resolveOutputPolicy`, `resolveManagedPath`, `ensureWithinRoot`, `isPathInside`, `isPathInsideWith`, `hasParentTraversal`, `ensureDirectory`, `readArchive` |
-| Option catalog | `UPSTREAM_OPTION_CATALOG`, `listLongFlags`, `findOptionByFlag`, `optionMetadata` |
-| Parsers | `parseJsonLines`, `sanitizeMetadataItem`, `sanitizeMetadataItems`, `paginate`, `parseFormats`, `parseSubtitles`, `parseThumbnails`, `parseProgress`, `parseFinalPaths` |
-| Process and errors | `runCommand`, `CommandExecutionError`, `toStructuredError` |
-| Redaction | `redactArgs`, `redactText`, `excerpt` |
-| Schemas and types | Zod input schemas and TypeScript interfaces exported from `src/index.ts` |
+| Workflow planning | `planWorkflow`, workflow input/plan/fact types |
+| Schemas | `WorkflowInspectInputSchema`, `WorkflowDownloadInputSchema`, `WorkflowExecutionInputSchema`, `WorkflowPostprocessInputSchema`, `WorkflowExpertInputSchema`, `WorkflowInputSchema`, `ValidateWorkflowInputSchema` |
+| Config | `loadConfig`, `CONFIG` from `yt-dlp-bridge/config` |
+| Environment | `checkEnvironment` from `yt-dlp-bridge/environment` |
+| Filesystem policy | `resolveOutputPolicy`, `resolveManagedPath`, `ensureWithinRoot`, `isPathInside`, `isPathInsideWith`, `hasParentTraversal`, `ensureDirectory`, `readArchive` from `yt-dlp-bridge/filesystem` |
+| Option catalog | `UPSTREAM_OPTION_CATALOG`, `listLongFlags`, `findOptionByFlag`, `optionMetadata` from `yt-dlp-bridge/option-catalog` |
+| Parsers | `parseYtDlpOutputLine`, `parseJsonLines`, `sanitizeMetadataItem`, `sanitizeMetadataItems`, `paginate`, `parseFormats`, `parseSubtitles`, `parseThumbnails`, `parseProgress`, `parseFinalPaths` from `yt-dlp-bridge/parsers` |
+| Runner | `runCommand`, `CommandExecutionError` from `yt-dlp-bridge/runner` |
+| Redaction | `redactArgs`, `redactText`, `excerpt` from `yt-dlp-bridge/redaction` |
+| Structured errors | `toStructuredError` from `yt-dlp-bridge/errors` |
+
+Example imports:
+
+```ts
+import { planWorkflow } from "yt-dlp-bridge";
+import { parseYtDlpOutputLine } from "yt-dlp-bridge/parsers";
+import { runCommand } from "yt-dlp-bridge/runner";
+import { redactArgs } from "yt-dlp-bridge/redaction";
+```
 
 ## Configuration
 
-`loadConfig()` reads environment variables and applies conservative defaults.
+`loadConfig(env?)` reads environment variables and applies conservative defaults. Pass a partial `ProcessEnv` object to override specific values.
 
 | Variable | Default | Purpose |
 | --- | --- | --- |
-| `YTDLP_MCP_YTDLP_PATH` or `YTDLP_PATH` | `yt-dlp` | Path or command name used for `yt-dlp`. |
+| `YTDLP_MCP_YTDLP_PATH` or `YTDLP_PATH` | `yt-dlp` | Path or command name for `yt-dlp`. |
 | `YTDLP_MCP_FFMPEG_PATH` or `FFMPEG_PATH` | `ffmpeg` | Optional ffmpeg override for environment checks. |
 | `YTDLP_MCP_FFPROBE_PATH` or `FFPROBE_PATH` | `ffprobe` | Optional ffprobe override for environment checks. |
 | `YTDLP_MCP_OUTPUT_ROOT` | `~/Downloads/yt-dlp-mcp` | Managed output root. |
-| `YTDLP_MCP_TEMP_ROOT` | OS temp directory under `yt-dlp-mcp` | Managed temp root. |
-| `YTDLP_MCP_ALLOW_ARBITRARY_OUTPUT_PATHS` | `false` | Allows output and temp paths outside the configured roots. |
-| `YTDLP_MCP_ALLOW_CONFIG_FILES` | `false` | Allows user-provided cookies, netrc, and related config-file inputs unless they match server-level settings. |
+| `YTDLP_MCP_TEMP_ROOT` | OS temp under `yt-dlp-mcp` | Managed temp root. |
+| `YTDLP_MCP_ALLOW_ARBITRARY_OUTPUT_PATHS` | `false` | Allow output paths outside the configured roots. |
+| `YTDLP_MCP_ALLOW_CONFIG_FILES` | `false` | Allow user-provided cookies, netrc, and config-file inputs. |
+| `YTDLP_MCP_ALLOW_PLUGIN_DIRS` | `false` | Allow user-provided plugin directory paths. |
 | `YTDLP_MCP_COOKIES_FILE` | unset | Server-level cookies file. |
 | `YTDLP_MCP_COOKIES_FROM_BROWSER` | unset | Server-level browser cookie source for `--cookies-from-browser`. |
-| `YTDLP_MCP_ENABLE_EXPERT` | `false` | Enables higher-risk expert-mode integrations in callers that expose them. |
-| `YTDLP_MCP_TIMEOUT_MS` | `900000` | Default command timeout. |
-| `YTDLP_MCP_MAX_OUTPUT_BYTES` | `4194304` | Maximum retained stdout or stderr bytes. |
+| `YTDLP_MCP_ENABLE_EXPERT` | `false` | Enable higher-risk expert-mode integrations. |
+| `YTDLP_MCP_TIMEOUT_MS` | `900000` | Default command timeout (ms). |
+| `YTDLP_MCP_MAX_OUTPUT_BYTES` | `4194304` | Maximum retained stdout/stderr bytes. |
 | `YTDLP_MCP_JS_RUNTIMES` | `deno,node,bun,quickjs` | JavaScript runtimes considered for extractor challenges. |
 
 ## Requirements
 
-- Node.js >= 22.13.
-- ESM import support.
-- `yt-dlp` installed when planning or running real yt-dlp workflows.
-- `ffmpeg` and `ffprobe` for audio extraction, audio/video merge, remuxing, recoding, segment editing, subtitle conversion, thumbnail conversion, and embedding workflows.
-- Python `yt_dlp` package, or `PYTHONPATH` pointed at a yt-dlp source checkout, when regenerating or verifying the option catalog.
+- Node.js >= 22.13, ESM.
+- `yt-dlp` installed when running yt-dlp workflows.
+- `ffmpeg` and `ffprobe` for audio extraction, merge, remux, recode, segment editing, subtitle/thumbnail conversion, and embedding workflows.
+- Python `yt_dlp` package, or `PYTHONPATH` pointing at a yt-dlp checkout, when regenerating or verifying the option catalog.
 
 ## Development
 
-| Command | Description |
-| --- | --- |
-| `pnpm run build` | Compile TypeScript and copy generated assets into `dist`. |
-| `pnpm test` | Run Vitest tests. |
-| `pnpm run typecheck` | Run TypeScript without emitting files. |
-| `pnpm run generate:options` | Regenerate the source-derived yt-dlp option catalog from Python `yt_dlp`. |
-| `pnpm run verify:options` | Verify that the generated option catalog matches Python `yt_dlp`. |
-| `pnpm pack --dry-run` | Preview the package contents before publishing. |
-
-## Release
-
-GitHub Actions handles CI and npm publishing:
-
-- `.github/workflows/ci.yml` runs typecheck, tests, build, and package dry-run on pull requests and pushes to `main`.
-- `.github/workflows/release.yml` publishes to npm when a `vX.Y.Z` tag is pushed and the tag matches `package.json`.
-- Publishing uses npm trusted publishing with GitHub Actions OIDC and publishes an attested npm tarball with `npm publish ./npm-artifacts/*.tgz --access public`; no `NPM_TOKEN` secret is required when the trusted publisher is configured. npm automatically generates provenance for trusted publishes from GitHub Actions.
-
-The npm trusted publisher should point at:
-
-```text
-repository: antonio-orionus/yt-dlp-bridge
-workflow file: release.yml
-environment: npm
-```
-
-Release flow:
-
 ```bash
-pnpm version patch
-git push origin main --follow-tags
+git clone https://github.com/antonio-orionus/Arroxy.git
+cd Arroxy
+bun install
 ```
 
-## Project Structure
-
-```text
-yt-dlp-bridge/
-├── .github/workflows/    # CI and npm publish automation
-├── src/                 # TypeScript source and generated option catalog
-├── tests/               # Vitest coverage for argv, policy, parsers, planning, and errors
-├── scripts/             # Option catalog generation and package asset scripts
-├── dist/                # Built package output
-├── package.json         # Package metadata, exports, scripts, and npm keywords
-└── README.md            # Package and repository documentation
-```
+| Command | Description |
+| --- | --- |
+| `bun run --filter yt-dlp-bridge build` | Compile TypeScript and copy generated assets into `dist`. |
+| `bun run --filter yt-dlp-bridge test` | Run Vitest tests. |
+| `bun run --filter yt-dlp-bridge typecheck` | TypeScript check without emitting. |
+| `bun run --filter yt-dlp-bridge generate:options` | Regenerate the option catalog from Python `yt_dlp`. |
+| `bun run --filter yt-dlp-bridge verify:options` | Verify the catalog matches Python `yt_dlp`. |
+| `bun run bridge:check` | Run the package gate used by Arroxy CI and registry publishing. |
 
 ## Troubleshooting
 
-### `yt-dlp` is missing
-
-Install `yt-dlp` or set `YTDLP_MCP_YTDLP_PATH` to the executable path. `checkEnvironment()` reports the detected command, status, version, and notes.
-
-### `ffmpeg` or `ffprobe` is missing
-
-Install the missing binary or set `YTDLP_MCP_FFMPEG_PATH` and `YTDLP_MCP_FFPROBE_PATH`. Planning still returns dependency information so callers can explain which workflow requires the missing tool.
-
-### `auth.cookiesFile requires YTDLP_MCP_ALLOW_CONFIG_FILES=true`
-
-User-provided config-file paths are blocked by default. Prefer server-level `YTDLP_MCP_COOKIES_FILE` or enable `YTDLP_MCP_ALLOW_CONFIG_FILES=true` only when the caller has reviewed the trust boundary.
+**`yt-dlp` is missing** - Install `yt-dlp` or set `YTDLP_MCP_YTDLP_PATH`. `checkEnvironment()` reports detected command, status, version, and notes.
 
-### `outputTemplate must not contain parent-directory traversal`
+**`ffmpeg`/`ffprobe` missing** - Install the binary or set `YTDLP_MCP_FFMPEG_PATH` / `YTDLP_MCP_FFPROBE_PATH`. Planning still returns dependency info so callers can surface which workflow requires the missing tool.
 
-Relative output templates cannot contain `..` path segments unless arbitrary output paths are explicitly allowed by policy.
+**`auth.cookiesFile requires YTDLP_MCP_ALLOW_CONFIG_FILES=true`** - User-provided config-file paths are blocked by default. Prefer server-level `YTDLP_MCP_COOKIES_FILE` or enable `YTDLP_MCP_ALLOW_CONFIG_FILES=true` only after reviewing the trust boundary.
 
-## Contributing
+**`outputTemplate must not contain parent-directory traversal`** - Relative templates cannot contain `..` segments unless `YTDLP_MCP_ALLOW_ARBITRARY_OUTPUT_PATHS=true`.
 
-Use the development commands above before opening a pull request. Bugs and feature requests can be reported through [GitHub Issues](https://github.com/antonio-orionus/yt-dlp-bridge/issues).
+Bugs and feature requests: [GitHub Issues](https://github.com/antonio-orionus/Arroxy/issues).
 
 ## License
 
-[MIT](LICENSE)
+[MIT](LICENSE) © 2026 Antonio Orionus

package/dist/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,YAAY;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,yBAAyB,EAAE,OAAO,CAAC;IACnC,gBAAgB,EAAE,OAAO,CAAC;IAC1B,eAAe,EAAE,OAAO,CAAC;IACzB,gBAAgB,EAAE,OAAO,CAAC;IAC1B,gBAAgB,EAAE,MAAM,CAAC;IACzB,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,kBAAkB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACxC,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB;AAWD,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAIhD;AAED,wBAAgB,UAAU,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,YAAY,CAiB7E;AAED,eAAO,MAAM,MAAM,cAAe,CAAC"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,YAAY;IAC5B,SAAS,EAAE,MAAM,CAAA;IACjB,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC/B,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAChC,UAAU,EAAE,MAAM,CAAA;IAClB,QAAQ,EAAE,MAAM,CAAA;IAChB,yBAAyB,EAAE,OAAO,CAAA;IAClC,gBAAgB,EAAE,OAAO,CAAA;IACzB,eAAe,EAAE,OAAO,CAAA;IACxB,gBAAgB,EAAE,OAAO,CAAA;IACzB,gBAAgB,EAAE,MAAM,CAAA;IACxB,cAAc,EAAE,MAAM,CAAA;IACtB,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAChC,kBAAkB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACvC,UAAU,EAAE,MAAM,EAAE,CAAA;CACpB;AA2BD,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAIhD;AAED,wBAAgB,UAAU,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,YAAY,CAoB7E;AAED,eAAO,MAAM,MAAM,cAAe,CAAA"}

package/dist/config.js

@@ -1,35 +1,54 @@
-import os from "node:os";
-import path from "node:path";
+import os from 'node:os';
+import path from 'node:path';
 function bool(value) {
-    return value ? ["1", "true", "yes", "on"].includes(value.toLowerCase()) : false;
+    const normalized = blankToUndefined(value);
+    return normalized ? ['1', 'true', 'yes', 'on'].includes(normalized.toLowerCase()) : false;
 }
 function int(value, fallback) {
-    const parsed = value ? Number.parseInt(value, 10) : Number.NaN;
+    const normalized = blankToUndefined(value);
+    const parsed = normalized ? Number.parseInt(normalized, 10) : Number.NaN;
     return Number.isFinite(parsed) ? parsed : fallback;
 }
+function blankToUndefined(value) {
+    const normalized = value?.trim();
+    if (!normalized)
+        return undefined;
+    return normalized;
+}
+function firstNonBlank(...values) {
+    for (const value of values) {
+        const normalized = blankToUndefined(value);
+        if (normalized !== undefined)
+            return normalized;
+    }
+    return undefined;
+}
 export function expandHome(input) {
-    if (input === "~")
+    if (input === '~')
         return os.homedir();
-    if (input.startsWith("~/") || input.startsWith("~\\"))
+    if (input.startsWith('~/') || input.startsWith('~\\'))
         return path.join(os.homedir(), input.slice(2));
     return input;
 }
 export function loadConfig(env = process.env) {
     return {
-        ytdlpPath: env.YTDLP_MCP_YTDLP_PATH ?? env.YTDLP_PATH ?? "yt-dlp",
-        ffmpegPath: env.YTDLP_MCP_FFMPEG_PATH ?? env.FFMPEG_PATH,
-        ffprobePath: env.YTDLP_MCP_FFPROBE_PATH ?? env.FFPROBE_PATH,
-        outputRoot: path.resolve(expandHome(env.YTDLP_MCP_OUTPUT_ROOT ?? path.join(os.homedir(), "Downloads", "yt-dlp-mcp"))),
-        tempRoot: path.resolve(expandHome(env.YTDLP_MCP_TEMP_ROOT ?? path.join(os.tmpdir(), "yt-dlp-mcp"))),
+        ytdlpPath: firstNonBlank(env.YTDLP_MCP_YTDLP_PATH, env.YTDLP_PATH) ?? 'yt-dlp',
+        ffmpegPath: firstNonBlank(env.YTDLP_MCP_FFMPEG_PATH, env.FFMPEG_PATH),
+        ffprobePath: firstNonBlank(env.YTDLP_MCP_FFPROBE_PATH, env.FFPROBE_PATH),
+        outputRoot: path.resolve(expandHome(firstNonBlank(env.YTDLP_MCP_OUTPUT_ROOT) ?? path.join(os.homedir(), 'Downloads', 'yt-dlp-mcp'))),
+        tempRoot: path.resolve(expandHome(firstNonBlank(env.YTDLP_MCP_TEMP_ROOT) ?? path.join(os.tmpdir(), 'yt-dlp-mcp'))),
         allowArbitraryOutputPaths: bool(env.YTDLP_MCP_ALLOW_ARBITRARY_OUTPUT_PATHS),
         allowConfigFiles: bool(env.YTDLP_MCP_ALLOW_CONFIG_FILES),
         allowPluginDirs: bool(env.YTDLP_MCP_ALLOW_PLUGIN_DIRS),
         enableExpertMode: bool(env.YTDLP_MCP_ENABLE_EXPERT),
         defaultTimeoutMs: int(env.YTDLP_MCP_TIMEOUT_MS, 15 * 60 * 1000),
         maxOutputBytes: int(env.YTDLP_MCP_MAX_OUTPUT_BYTES, 4 * 1024 * 1024),
-        cookiesFile: env.YTDLP_MCP_COOKIES_FILE,
-        cookiesFromBrowser: env.YTDLP_MCP_COOKIES_FROM_BROWSER,
-        jsRuntimes: (env.YTDLP_MCP_JS_RUNTIMES ?? "deno,node,bun,quickjs").split(",").map((v) => v.trim()).filter(Boolean)
+        cookiesFile: firstNonBlank(env.YTDLP_MCP_COOKIES_FILE),
+        cookiesFromBrowser: firstNonBlank(env.YTDLP_MCP_COOKIES_FROM_BROWSER),
+        jsRuntimes: (firstNonBlank(env.YTDLP_MCP_JS_RUNTIMES) ?? 'deno,node,bun,quickjs')
+            .split(',')
+            .map(v => v.trim())
+            .filter(Boolean)
     };
 }
 export const CONFIG = loadConfig();

package/dist/config.js.map

@@ -1 +1 @@
-{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAmB7B,SAAS,IAAI,CAAC,KAAyB;IACrC,OAAO,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;AAClF,CAAC;AAED,SAAS,GAAG,CAAC,KAAyB,EAAE,QAAgB;IACtD,MAAM,MAAM,GAAG,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC;IAC/D,OAAO,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC;AACrD,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,KAAa;IACtC,IAAI,KAAK,KAAK,GAAG;QAAE,OAAO,EAAE,CAAC,OAAO,EAAE,CAAC;IACvC,IAAI,KAAK,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,KAAK,CAAC,UAAU,CAAC,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IACtG,OAAO,KAAK,CAAC;AACf,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,MAAyB,OAAO,CAAC,GAAG;IAC7D,OAAO;QACL,SAAS,EAAE,GAAG,CAAC,oBAAoB,IAAI,GAAG,CAAC,UAAU,IAAI,QAAQ;QACjE,UAAU,EAAE,GAAG,CAAC,qBAAqB,IAAI,GAAG,CAAC,WAAW;QACxD,WAAW,EAAE,GAAG,CAAC,sBAAsB,IAAI,GAAG,CAAC,YAAY;QAC3D,UAAU,EAAE,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC,qBAAqB,IAAI,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,WAAW,EAAE,YAAY,CAAC,CAAC,CAAC;QACrH,QAAQ,EAAE,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC,mBAAmB,IAAI,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,MAAM,EAAE,EAAE,YAAY,CAAC,CAAC,CAAC;QACnG,yBAAyB,EAAE,IAAI,CAAC,GAAG,CAAC,sCAAsC,CAAC;QAC3E,gBAAgB,EAAE,IAAI,CAAC,GAAG,CAAC,4BAA4B,CAAC;QACxD,eAAe,EAAE,IAAI,CAAC,GAAG,CAAC,2BAA2B,CAAC;QACtD,gBAAgB,EAAE,IAAI,CAAC,GAAG,CAAC,uBAAuB,CAAC;QACnD,gBAAgB,EAAE,GAAG,CAAC,GAAG,CAAC,oBAAoB,EAAE,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;QAC/D,cAAc,EAAE,GAAG,CAAC,GAAG,CAAC,0BAA0B,EAAE,CAAC,GAAG,IAAI,GAAG,IAAI,CAAC;QACpE,WAAW,EAAE,GAAG,CAAC,sBAAsB;QACvC,kBAAkB,EAAE,GAAG,CAAC,8BAA8B;QACtD,UAAU,EAAE,CAAC,GAAG,CAAC,qBAAqB,IAAI,uBAAuB,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC;KACnH,CAAC;AACJ,CAAC;AAED,MAAM,CAAC,MAAM,MAAM,GAAG,UAAU,EAAE,CAAC"}
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,SAAS,CAAA;AACxB,OAAO,IAAI,MAAM,WAAW,CAAA;AAmB5B,SAAS,IAAI,CAAC,KAAyB;IACtC,MAAM,UAAU,GAAG,gBAAgB,CAAC,KAAK,CAAC,CAAA;IAC1C,OAAO,UAAU,CAAC,CAAC,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,CAAC,CAAC,QAAQ,CAAC,UAAU,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,CAAC,KAAK,CAAA;AAC1F,CAAC;AAED,SAAS,GAAG,CAAC,KAAyB,EAAE,QAAgB;IACvD,MAAM,UAAU,GAAG,gBAAgB,CAAC,KAAK,CAAC,CAAA;IAC1C,MAAM,MAAM,GAAG,UAAU,CAAC,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAA;IACxE,OAAO,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAA;AACnD,CAAC;AAED,SAAS,gBAAgB,CAAC,KAAyB;IAClD,MAAM,UAAU,GAAG,KAAK,EAAE,IAAI,EAAE,CAAA;IAChC,IAAI,CAAC,UAAU;QAAE,OAAO,SAAS,CAAA;IACjC,OAAO,UAAU,CAAA;AAClB,CAAC;AAED,SAAS,aAAa,CAAC,GAAG,MAA8B;IACvD,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC5B,MAAM,UAAU,GAAG,gBAAgB,CAAC,KAAK,CAAC,CAAA;QAC1C,IAAI,UAAU,KAAK,SAAS;YAAE,OAAO,UAAU,CAAA;IAChD,CAAC;IACD,OAAO,SAAS,CAAA;AACjB,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,KAAa;IACvC,IAAI,KAAK,KAAK,GAAG;QAAE,OAAO,EAAE,CAAC,OAAO,EAAE,CAAA;IACtC,IAAI,KAAK,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,KAAK,CAAC,UAAU,CAAC,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAA;IACrG,OAAO,KAAK,CAAA;AACb,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,MAAyB,OAAO,CAAC,GAAG;IAC9D,OAAO;QACN,SAAS,EAAE,aAAa,CAAC,GAAG,CAAC,oBAAoB,EAAE,GAAG,CAAC,UAAU,CAAC,IAAI,QAAQ;QAC9E,UAAU,EAAE,aAAa,CAAC,GAAG,CAAC,qBAAqB,EAAE,GAAG,CAAC,WAAW,CAAC;QACrE,WAAW,EAAE,aAAa,CAAC,GAAG,CAAC,sBAAsB,EAAE,GAAG,CAAC,YAAY,CAAC;QACxE,UAAU,EAAE,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,aAAa,CAAC,GAAG,CAAC,qBAAqB,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,WAAW,EAAE,YAAY,CAAC,CAAC,CAAC;QACpI,QAAQ,EAAE,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,aAAa,CAAC,GAAG,CAAC,mBAAmB,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,MAAM,EAAE,EAAE,YAAY,CAAC,CAAC,CAAC;QAClH,yBAAyB,EAAE,IAAI,CAAC,GAAG,CAAC,sCAAsC,CAAC;QAC3E,gBAAgB,EAAE,IAAI,CAAC,GAAG,CAAC,4BAA4B,CAAC;QACxD,eAAe,EAAE,IAAI,CAAC,GAAG,CAAC,2BAA2B,CAAC;QACtD,gBAAgB,EAAE,IAAI,CAAC,GAAG,CAAC,uBAAuB,CAAC;QACnD,gBAAgB,EAAE,GAAG,CAAC,GAAG,CAAC,oBAAoB,EAAE,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;QAC/D,cAAc,EAAE,GAAG,CAAC,GAAG,CAAC,0BAA0B,EAAE,CAAC,GAAG,IAAI,GAAG,IAAI,CAAC;QACpE,WAAW,EAAE,aAAa,CAAC,GAAG,CAAC,sBAAsB,CAAC;QACtD,kBAAkB,EAAE,aAAa,CAAC,GAAG,CAAC,8BAA8B,CAAC;QACrE,UAAU,EAAE,CAAC,aAAa,CAAC,GAAG,CAAC,qBAAqB,CAAC,IAAI,uBAAuB,CAAC;aAC/E,KAAK,CAAC,GAAG,CAAC;aACV,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;aAClB,MAAM,CAAC,OAAO,CAAC;KACjB,CAAA;AACF,CAAC;AAED,MAAM,CAAC,MAAM,MAAM,GAAG,UAAU,EAAE,CAAA"}

package/dist/environment.d.ts

@@ -1,5 +1,5 @@
-import { type ServerConfig } from "./config.js";
-import type { DetectedDependency } from "./types.js";
+import { type ServerConfig } from './config.js';
+import type { DetectedDependency } from './types.js';
 export interface EnvironmentReport {
     platform: NodeJS.Platform;
     arch: string;