### Install Dependencies and Start Development Server

Source: https://github.com/gentleman-programming/tubemaster/blob/feature-2/CONTRIBUTING.md

Run these commands to set up the project locally and start the development server. Ensure you have Node.js installed.

```bash
npm install
npm run dev
```

--------------------------------

### Start TubeMaster MCP Server

Source: https://github.com/gentleman-programming/tubemaster/blob/feature-2/README.md

Command to start the MCP server for agent and tool integrations. This server communicates over stdio.

```bash
npm run mcp:video-metadata
```

--------------------------------

### Generate YouTube Video Preview via CLI

Source: https://github.com/gentleman-programming/tubemaster/blob/feature-2/README.md

Command to generate a preview for a YouTube video, allowing for an editorial prompt to guide the preview generation.

```bash
npm run cli:video-metadata -- preview --videoId <VIDEO_ID> --editorialPrompt "Hacé un título claro"
```

--------------------------------

### Sign in to Web UI

Source: https://github.com/gentleman-programming/tubemaster/blob/feature-2/docs/troubleshooting.md

If authentication fails in the Web UI, sign in again starting from the root path.

```bash
sign in again from '/'
```

--------------------------------

### API Metadata Request Body Examples

Source: https://github.com/gentleman-programming/tubemaster/blob/feature-2/docs/interfaces.md

Examples of JSON request bodies for metadata-related API endpoints. Ensure videoId and other required fields are provided.

```json
{
  "videoId": "..."
}
```

```json
{
  "videoId": "...",
  "editorialPrompt": "..."
}
```

```json
{
  "videoId": "...",
  "finalTitle": "...",
  "description": "...",
  "expectedChannelId": "UC...",
  "dryRun": true|false
}
```

--------------------------------

### Playlist API - Get Videos

Source: https://github.com/gentleman-programming/tubemaster/blob/feature-2/docs/interfaces.md

Retrieves a list of videos. Used by the Web UI.

```APIDOC
## GET /api/youtube/videos

### Description
Retrieves a list of videos. This endpoint is used by the Web UI.

### Method
GET

### Endpoint
/api/youtube/videos

### Response
#### Success Response (200)
- **videos** (array) - A list of video objects.

#### Response Example
```json
{
  "videos": [
    {
      "id": "...",
      "title": "..."
    }
  ]
}
```
```

--------------------------------

### Playlist API - Get Playlists

Source: https://github.com/gentleman-programming/tubemaster/blob/feature-2/docs/interfaces.md

Retrieves a list of playlists. Used by the Web UI.

```APIDOC
## GET /api/youtube/playlists

### Description
Retrieves a list of playlists. This endpoint is used by the Web UI.

### Method
GET

### Endpoint
/api/youtube/playlists

### Response
#### Success Response (200)
- **playlists** (array) - A list of playlist objects.

#### Response Example
```json
{
  "playlists": [
    {
      "id": "...",
      "title": "..."
    }
  ]
}
```
```

--------------------------------

### Metadata API - Get Video Transcript

Source: https://github.com/gentleman-programming/tubemaster/blob/feature-2/docs/interfaces.md

Retrieves the transcript for a given video. Requires an authenticated session user.

```APIDOC
## POST /api/video-metadata/transcript

### Description
Retrieves the transcript for a given video.

### Method
POST

### Endpoint
/api/video-metadata/transcript

### Request Body
- **videoId** (string) - Required - The ID of the video for which to retrieve the transcript.

### Request Example
```json
{
  "videoId": "..."
}
```

### Response
#### Success Response (200)
- **transcript** (string) - The transcript of the video.

#### Response Example
```json
{
  "transcript": "The full transcript of the video..."
}
```
```

--------------------------------

### Playlist API - Get Channel Info

Source: https://github.com/gentleman-programming/tubemaster/blob/feature-2/docs/interfaces.md

Retrieves information about a YouTube channel. Used by the Web UI.

```APIDOC
## GET /api/youtube/channel-info

### Description
Retrieves information about a YouTube channel. This endpoint is used by the Web UI.

### Method
GET

### Endpoint
/api/youtube/channel-info

### Response
#### Success Response (200)
- **channelInfo** (object) - An object containing channel information.

#### Response Example
```json
{
  "channelInfo": {
    "id": "UC...",
    "title": "Channel Title"
  }
}
```
```

--------------------------------

### Get Write Channel Context Matched Alignment Test Case

Source: https://github.com/gentleman-programming/tubemaster/blob/feature-2/openspec/changes/archive/2026-04-24-youtube-select-write-channel/verify-report.md

This test case verifies that getWriteChannelContext returns matched alignment when the expected channel equals the active channel. It is part of the youtube-write-channel-guardrails feature.

```typescript
src/lib/write-context/service.test.ts > getWriteChannelContext returns matched alignment when expected equals active
```

--------------------------------

### Configure Local Environment Variables

Source: https://github.com/gentleman-programming/tubemaster/blob/feature-2/docs/getting-started.md

Set up your local environment by creating a `.env.local` file with your Google OAuth credentials and NextAuth configuration. Required variables are used for OAuth and session management.

```dotenv
GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=your-client-secret
NEXTAUTH_URL=http://localhost:3000
NEXTAUTH_SECRET=replace-with-a-long-random-secret

# Optional
# CLI_OAUTH_CALLBACK_PORT=8787
# YOUTUBE_TRANSCRIPT_PROVIDER=youtube-captions
# METADATA_GENERATOR_MODE=rule-based
# METADATA_GENERATOR_RAW_OUTPUT={"finalTitle":"...","description":"...","promptVersion":"..."}
```

--------------------------------

### Basic TubeMaster Project Commands

Source: https://github.com/gentleman-programming/tubemaster/blob/feature-2/README.md

Common commands for running tests, linting, and the development server for the TubeMaster project.

```bash
npm run dev
npm run test
npm run lint
```

--------------------------------

### Create a YouTube Playlist via CLI

Source: https://github.com/gentleman-programming/tubemaster/blob/feature-2/README.md

Command to create a new YouTube playlist with a specified title, description, and privacy status using the TubeMaster CLI. Requires `expectedChannelId` for safety.

```bash
npm run cli:video-metadata -- playlist create --title "Roadtrip 2026" --description "Videos del viaje" --expectedChannelId <CHANNEL_ID> --privacyStatus unlisted
```

--------------------------------

### CLI Metadata Commands

Source: https://github.com/gentleman-programming/tubemaster/blob/feature-2/docs/interfaces.md

Retrieve video metadata, transcripts, generate previews with editorial prompts, and apply metadata changes. Use `--dryRun` to test changes without applying them.

```bash
npm run cli:video-metadata -- list [--channelId <CHANNEL_ID>] [--maxResults 25] [--userId <USER_ID>]
npm run cli:video-metadata -- transcript --videoId <VIDEO_ID> [--userId <USER_ID>]
npm run cli:video-metadata -- preview --videoId <VIDEO_ID> --editorialPrompt "..." [--userId <USER_ID>]
npm run cli:video-metadata -- apply --videoId <VIDEO_ID> --finalTitle "..." --description "..." --expectedChannelId <UC...> [--dryRun] [--userId <USER_ID>]
```

--------------------------------

### Apply Metadata Changes to YouTube Video via CLI

Source: https://github.com/gentleman-programming/tubemaster/blob/feature-2/README.md

Command to apply new metadata (title, description) to a YouTube video. Includes `expectedChannelId` for safety and a `dryRun` option for testing.

```bash
npm run cli:video-metadata -- apply --videoId <VIDEO_ID> --finalTitle "Nuevo título" --description "Nueva descripción" --expectedChannelId <CHANNEL_ID> --dryRun
```

--------------------------------

### List Available Channels via CLI

Source: https://github.com/gentleman-programming/tubemaster/blob/feature-2/docs/troubleshooting.md

Retrieve a list of available channels that can be selected for operations.

```bash
npm run cli:video-metadata -- auth list-channels
```

--------------------------------

### Get Write Channel Context Unresolved Test Case

Source: https://github.com/gentleman-programming/tubemaster/blob/feature-2/openspec/changes/archive/2026-04-24-youtube-select-write-channel/verify-report.md

This test case checks if getWriteChannelContext returns unresolved without reauthentication when the expected channel is missing. It is part of the youtube-write-channel-guardrails feature.

```typescript
src/lib/write-context/service.test.ts > getWriteChannelContext returns unresolved without reauth when expected is missing
```

--------------------------------

### CLI Playlist Commands

Source: https://github.com/gentleman-programming/tubemaster/blob/feature-2/docs/interfaces.md

Manage YouTube playlists, including listing, creating, updating, deleting, adding videos, and removing videos. Specify privacy status during creation or update.

```bash
npm run cli:video-metadata -- playlist list [--userId <USER_ID>]
npm run cli:video-metadata -- playlist create --title "..." --expectedChannelId <UC...> [--description "..."] [--privacyStatus private|public|unlisted] [--userId <USER_ID>]
npm run cli:video-metadata -- playlist update --playlistId <PLAYLIST_ID> --expectedChannelId <UC...> [--title "..."] [--description "..."] [--privacyStatus private|public|unlisted] [--userId <USER_ID>]
npm run cli:video-metadata -- playlist delete --playlistId <PLAYLIST_ID> --expectedChannelId <UC...> [--userId <USER_ID>]
npm run cli:video-metadata -- playlist add --playlistId <PLAYLIST_ID> --videoIds <VIDEO1,VIDEO2,...> [--userId <USER_ID>]
npm run cli:video-metadata -- playlist remove --playlistId <PLAYLIST_ID> --videoIds <VIDEO1,VIDEO2,...> [--userId <USER_ID>]
```

--------------------------------

### Run Tests

Source: https://github.com/gentleman-programming/tubemaster/blob/feature-2/openspec/changes/archive/2026-04-23-cli-auth-bootstrap/verify-report.md

Execute the test suite to verify the functionality of the codebase. This command runs all tests and reports the number of passed, failed, and skipped tests.

```bash
npm test
```

--------------------------------

### CLI Authentication Commands

Source: https://github.com/gentleman-programming/tubemaster/blob/feature-2/docs/interfaces.md

Manage user authentication, view current user, and select channels via the command-line interface. Use `--device` for device-based authentication.

```bash
npm run cli:video-metadata -- auth login
npm run cli:video-metadata -- auth login --device
npm run cli:video-metadata -- auth whoami
npm run cli:video-metadata -- auth list-users
npm run cli:video-metadata -- auth select-user --userId <USER_ID>
npm run cli:video-metadata -- auth list-channels
npm run cli:video-metadata -- auth select-channel --channelId <UC...>
npm run cli:video-metadata -- auth logout
npm run cli:video-metadata -- auth revoke [--userId <USER_ID>]
```

--------------------------------

### Add Videos to a YouTube Playlist via CLI

Source: https://github.com/gentleman-programming/tubemaster/blob/feature-2/README.md

Command to add one or more videos to a specified YouTube playlist using their IDs.

```bash
npm run cli:video-metadata -- playlist add --playlistId <PLAYLIST_ID> --videoIds <VIDEO_ID_1>,<VIDEO_ID_2>
```

--------------------------------

### Login to CLI

Source: https://github.com/gentleman-programming/tubemaster/blob/feature-2/docs/troubleshooting.md

Use this command to log in via the CLI. This is often required after authentication errors or to re-authenticate with new scopes.

```bash
npm run cli:video-metadata -- auth login
```

--------------------------------

### Run Lightweight Checks Before PR

Source: https://github.com/gentleman-programming/tubemaster/blob/feature-2/CONTRIBUTING.md

Execute these commands to perform tests and linting before submitting a pull request. This helps ensure code quality and adherence to standards.

```bash
npm run test
npm run lint
```

--------------------------------

### Retrieve YouTube Video Transcript via CLI

Source: https://github.com/gentleman-programming/tubemaster/blob/feature-2/README.md

Command to fetch the transcript for a given YouTube video ID.

```bash
npm run cli:video-metadata -- transcript --videoId <VIDEO_ID>
```

--------------------------------

### CLI Auth Commands Implementation

Source: https://github.com/gentleman-programming/tubemaster/blob/feature-2/openspec/changes/archive/2026-04-23-cli-auth-bootstrap/verify-report.md

This note indicates that the CLI 'auth' namespace commands, including login, whoami, list-users, logout, and revoke, are implemented in the specified file.

```typescript
src/cli/video-metadata.ts
```

--------------------------------

### Playlist API - Create Playlist

Source: https://github.com/gentleman-programming/tubemaster/blob/feature-2/docs/interfaces.md

Creates a new playlist. Used by the Web UI.

```APIDOC
## POST /api/youtube/create-playlist

### Description
Creates a new playlist. This endpoint is used by the Web UI.

### Method
POST

### Endpoint
/api/youtube/create-playlist

### Request Body
- **title** (string) - Required - The title of the new playlist.
- **description** (string) - Optional - The description of the new playlist.
- **privacyStatus** (string) - Optional - The privacy status of the playlist (private, public, unlisted).

### Request Example
```json
{
  "title": "My New Playlist",
  "description": "A collection of my favorite videos.",
  "privacyStatus": "public"
}
```

### Response
#### Success Response (200)
- **playlistId** (string) - The ID of the newly created playlist.

#### Response Example
```json
{
  "playlistId": "PL..."
}
```
```

--------------------------------

### Run Linting

Source: https://github.com/gentleman-programming/tubemaster/blob/feature-2/openspec/changes/archive/2026-04-23-cli-auth-bootstrap/verify-report.md

Execute the linting process to check for code style and potential errors. This is part of the build and test execution phase.

```bash
npm run lint
```

--------------------------------

### Update an Existing YouTube Playlist via CLI

Source: https://github.com/gentleman-programming/tubemaster/blob/feature-2/README.md

Command to update the description of an existing YouTube playlist using its ID and the `expectedChannelId` for verification.

```bash
npm run cli:video-metadata -- playlist update --playlistId <PLAYLIST_ID> --expectedChannelId <CHANNEL_ID> --description "Nueva descripción"
```

--------------------------------

### MCP Tool for Listing Channels

Source: https://github.com/gentleman-programming/tubemaster/blob/feature-2/openspec/changes/archive/2026-04-24-youtube-select-write-channel/design.md

MCP tool to list write channels. Input is an empty object.

```json
write_channel_list input {}
```

--------------------------------

### Authenticate and Verify CLI Access

Source: https://github.com/gentleman-programming/tubemaster/blob/feature-2/README.md

Commands to log in and check the current authenticated user via the TubeMaster CLI.

```bash
npm run cli:video-metadata -- auth login
npm run cli:video-metadata -- auth whoami
```

--------------------------------

### Run Quality Gate Checks

Source: https://github.com/gentleman-programming/tubemaster/blob/feature-2/openspec/changes/archive/2026-04-23-video-metadata-cli-mcp/apply-progress.md

Execute automated tests, linting, and TypeScript compilation checks.

```bash
npm test          # ✅ pass (21 tests)
npm run lint      # ✅ pass
npx tsc --noEmit  # ✅ pass
```

--------------------------------

### Authenticate CLI User

Source: https://github.com/gentleman-programming/tubemaster/blob/feature-2/docs/getting-started.md

Log in to TubeMaster using the CLI via loopback OAuth, which opens a browser for authentication. Alternatively, use the device flow for authentication.

```bash
npm run cli:video-metadata -- auth login
```

```bash
npm run cli:video-metadata -- auth login --device
```

--------------------------------

### MCP Tool for Write Context

Source: https://github.com/gentleman-programming/tubemaster/blob/feature-2/openspec/changes/archive/2026-04-24-youtube-select-write-channel/design.md

The existing write_context MCP tool, now returning the enriched contract.

```json
write_context remains, but returns the enriched contract above.
```

--------------------------------

### CLI Command for Selecting a Channel

Source: https://github.com/gentleman-programming/tubemaster/blob/feature-2/openspec/changes/archive/2026-04-24-youtube-select-write-channel/design.md

Command to select a specific write channel by its ID. Ensure the CLI is executed with the correct npm script and the channel ID is provided.

```bash
npm run cli:video-metadata -- auth select-channel --channelId <CHANNEL_ID>
```

--------------------------------

### Rules API - Run Matching Engine

Source: https://github.com/gentleman-programming/tubemaster/blob/feature-2/docs/interfaces.md

Executes the rule matching engine over recent videos. Used by the Web UI.

```APIDOC
## POST /api/run

### Description
Executes the rule matching engine over recent videos. This endpoint is used by the Web UI.

### Method
POST

### Endpoint
/api/run

### Response
#### Success Response (200)
- **message** (string) - A confirmation message indicating the matching engine has run.

#### Response Example
```json
{
  "message": "Rule matching engine executed."
}
```
```

--------------------------------

### Run Tests Command

Source: https://github.com/gentleman-programming/tubemaster/blob/feature-2/openspec/changes/transcript-diagnostics/verify-report.md

Command to execute tests using Node.js with tsx.

```text
node --import tsx --test "src/**/*.test.ts"
```

--------------------------------

### Metadata API - Apply Video Edits

Source: https://github.com/gentleman-programming/tubemaster/blob/feature-2/docs/interfaces.md

Applies final edits to a video, including title and description. Requires an authenticated session user.

```APIDOC
## POST /api/video-metadata/apply

### Description
Applies final edits to a video, including title and description.

### Method
POST

### Endpoint
/api/video-metadata/apply

### Request Body
- **videoId** (string) - Required - The ID of the video to apply edits to.
- **finalTitle** (string) - Required - The new title for the video.
- **description** (string) - Required - The new description for the video.
- **expectedChannelId** (string) - Required - The expected channel ID for the video.
- **dryRun** (boolean) - Optional - If true, performs a dry run without applying changes.

### Request Example
```json
{
  "videoId": "...",
  "finalTitle": "...",
  "description": "...",
  "expectedChannelId": "UC...",
  "dryRun": false
}
```

### Response
#### Success Response (200)
- **message** (string) - A confirmation message indicating the edits were applied or a dry run was completed.

#### Response Example
```json
{
  "message": "Video edits applied successfully."
}
```
```

--------------------------------

### MCP Tool for Selecting a Channel

Source: https://github.com/gentleman-programming/tubemaster/blob/feature-2/openspec/changes/archive/2026-04-24-youtube-select-write-channel/design.md

MCP tool to select a write channel. Requires a channelId and optionally accepts a credentialRef.

```json
write_channel_select input { channelId: z.string().min(1), credentialRef?: credentialSchema }
```

--------------------------------

### Perform Read-Only Playlist Listing

Source: https://github.com/gentleman-programming/tubemaster/blob/feature-2/docs/getting-started.md

Execute a read-only command to list playlists. This is a safe operation that does not modify any data.

```bash
npm run cli:video-metadata -- playlist list
```

--------------------------------

### Review Metadata Changes with Dry Run

Source: https://github.com/gentleman-programming/tubemaster/blob/feature-2/docs/getting-started.md

Apply metadata changes to a video without actually committing them. The `--dryRun` flag allows you to preview the proposed changes, including the final title, description, and expected channel ID, before they are applied.

```bash
npm run cli:video-metadata -- apply --videoId <VIDEO_ID> --finalTitle "Draft title" --description "Draft description" --expectedChannelId <UC...> --dryRun
```

--------------------------------

### CLI Fallback to Active Auth Context Test

Source: https://github.com/gentleman-programming/tubemaster/blob/feature-2/openspec/changes/archive/2026-04-23-cli-auth-bootstrap/verify-report.md

This test case verifies that CLI commands like 'transcript', 'preview', and 'apply' fall back to using the active authentication context when the `--userId` flag is omitted.

```typescript
src/cli/video-metadata.test.ts > CLI transcript/preview/apply fallback to active auth context when --userId is omitted
```

--------------------------------

### Playlist API - Add Videos to Playlist

Source: https://github.com/gentleman-programming/tubemaster/blob/feature-2/docs/interfaces.md

Adds videos to an existing playlist. Used by the Web UI.

```APIDOC
## POST /api/youtube/add-to-playlist

### Description
Adds videos to an existing playlist. This endpoint is used by the Web UI.

### Method
POST

### Endpoint
/api/youtube/add-to-playlist

### Request Body
- **playlistId** (string) - Required - The ID of the playlist to add videos to.
- **videoIds** (array) - Required - A list of video IDs to add to the playlist.

### Request Example
```json
{
  "playlistId": "PL...",
  "videoIds": ["VIDEO_ID_1", "VIDEO_ID_2"]
}
```

### Response
#### Success Response (200)
- **message** (string) - A confirmation message indicating the videos were added.

#### Response Example
```json
{
  "message": "Videos added to playlist successfully."
}
```
```

--------------------------------

### Metadata API - Preview Video Edit

Source: https://github.com/gentleman-programming/tubemaster/blob/feature-2/docs/interfaces.md

Generates a preview of potential edits for a video based on an editorial prompt. Requires an authenticated session user.

```APIDOC
## POST /api/video-metadata/preview

### Description
Generates a preview of potential edits for a video based on an editorial prompt.

### Method
POST

### Endpoint
/api/video-metadata/preview

### Request Body
- **videoId** (string) - Required - The ID of the video to preview edits for.
- **editorialPrompt** (string) - Required - The prompt guiding the editorial changes.

### Request Example
```json
{
  "videoId": "...",
  "editorialPrompt": "..."
}
```

### Response
#### Success Response (200)
- **preview** (string) - A preview of the suggested edits.

#### Response Example
```json
{
  "preview": "Suggested edits based on the prompt..."
}
```
```

--------------------------------

### Set Active Channel Context for CLI

Source: https://github.com/gentleman-programming/tubemaster/blob/feature-2/docs/getting-started.md

List available channels and select a specific channel for write operations. This is a safety measure to prevent accidental modifications to the wrong channel.

```bash
npm run cli:video-metadata -- auth list-channels
```

```bash
npm run cli:video-metadata -- auth select-channel --channelId <UC...>
```

--------------------------------

### Linting Tool

Source: https://github.com/gentleman-programming/tubemaster/blob/feature-2/openspec/changes/transcript-diagnostics/verify-report.md

Indicates that ESLint is used for linting.

```text
eslint
```

--------------------------------

### CLI Auth Test Case

Source: https://github.com/gentleman-programming/tubemaster/blob/feature-2/openspec/changes/archive/2026-04-24-youtube-select-write-channel/verify-report.md

This test case verifies that CLI authentication supports various commands like whoami, list-users, logout, and revoke with stable envelopes. It is part of the playlist-management-cli feature.

```typescript
src/cli/video-metadata.test.ts > CLI auth supports whoami/list-users/logout/revoke with stable envelopes
```

--------------------------------

### CLI Auth Login Default Loopback Test

Source: https://github.com/gentleman-programming/tubemaster/blob/feature-2/openspec/changes/archive/2026-04-23-cli-auth-bootstrap/verify-report.md

This test case verifies that the CLI authentication login command, when using the default loopback flow, returns a stable success envelope.

```typescript
src/cli/video-metadata.test.ts > CLI auth login default uses loopback flow and returns stable success envelope
```

--------------------------------

### Test Execution Summary

Source: https://github.com/gentleman-programming/tubemaster/blob/feature-2/openspec/changes/archive/2026-04-23-video-metadata-cli-mcp/verify-report.md

This output shows the results of the automated test suite execution. It indicates the number of passed, failed, and skipped tests.

```text
✔ CLI list command calls core listVideos and returns structured JSON
✔ CLI returns validation error and non-zero exit for missing required flags
✔ CLI apply dry-run forwards dryRun=true and returns proposal
✔ resolveGoogleCredentials returns usable auth context for non-web adapters
✔ resolveGoogleCredentials rejects credentials with insufficient scopes
✔ resolveGoogleCredentials fails consistently when token is expired and cannot refresh
✔ metadata generator returns valid draft in rule-based mode
✔ metadata generator rejects malformed raw-json as validation_failed
✔ listVideos returns typed list when credentials are valid
✔ listVideos maps unknown adapter errors to unauthorized
✔ getTranscript keeps available status
✔ getTranscript keeps unavailable status
✔ getTranscript keeps unsupported status
✔ previewMetadata returns one finalTitle and one description
✔ previewMetadata remains enabled when transcript is unavailable
✔ previewMetadata remains enabled when transcript provider is unsupported
✔ applyMetadata dryRun proposes title/description and avoids remote mutation
✔ applyMetadata updates only title/description while preserving snippet fields
✔ MCP preview tool returns finalTitle and description for valid input
✔ MCP handlers reject invalid input with structured validation error
✔ MCP apply tool supports dry-run review without mutation
ℹ tests 21
ℹ pass 21, fail 0, skipped 0
```

--------------------------------

### Select Channel for CLI Operations

Source: https://github.com/gentleman-programming/tubemaster/blob/feature-2/docs/troubleshooting.md

Persist a channel selection for subsequent CLI mutation commands. Replace `<UC...>` with the actual channel ID.

```bash
npm run cli:video-metadata -- auth select-channel --channelId <UC...>
```

--------------------------------

### Test Output Summary

Source: https://github.com/gentleman-programming/tubemaster/blob/feature-2/openspec/changes/archive/2026-04-24-youtube-select-write-channel/verify-report.md

This output summarizes the results of the test execution, indicating the total number of tests, passed tests, failed tests, and skipped tests.

```text
ℹ tests 138
ℹ pass 138
ℹ fail 0
ℹ skipped 0
```

--------------------------------

### Verify Active CLI Identity

Source: https://github.com/gentleman-programming/tubemaster/blob/feature-2/docs/getting-started.md

Check the currently authenticated user for the CLI. This command helps verify that your login was successful.

```bash
npm run cli:video-metadata -- auth whoami
```

--------------------------------

### CLI Auth Select Channel Test Case

Source: https://github.com/gentleman-programming/tubemaster/blob/feature-2/openspec/changes/archive/2026-04-24-youtube-select-write-channel/verify-report.md

This test case checks if the CLI select-channel command persists the expected channel and returns mismatch guidance. It is part of the playlist-management-cli feature.

```typescript
src/cli/video-metadata.test.ts > CLI auth select-channel persists expected channel and returns mismatch guidance
```

--------------------------------

### Apply Expected Channel ID to Mutation Command

Source: https://github.com/gentleman-programming/tubemaster/blob/feature-2/docs/troubleshooting.md

When performing write operations via the CLI, specify the expected channel ID to prevent guardrail errors. Replace `<UC...>` with the actual channel ID.

```bash
--expectedChannelId <UC...>
```

--------------------------------

### List Known Channels Merge Test Case

Source: https://github.com/gentleman-programming/tubemaster/blob/feature-2/openspec/changes/archive/2026-04-24-youtube-select-write-channel/verify-report.md

This test case verifies that listKnownChannels merges selected and active channels with deduplication and source tagging. It is part of the cli-auth-bootstrap feature.

```typescript
src/lib/write-context/service.test.ts > listKnownChannels merges selected + active channels with dedupe and source tagging
```

--------------------------------

### CLI Auth Unknown Subcommand Test

Source: https://github.com/gentleman-programming/tubemaster/blob/feature-2/openspec/changes/archive/2026-04-23-cli-auth-bootstrap/verify-report.md

This test case ensures that the CLI rejects unknown subcommands within the 'auth' namespace.

```typescript
src/cli/video-metadata.test.ts > CLI auth rejects unknown auth subcommand
```

--------------------------------

### CLI Select Write Channel Persist Test Case

Source: https://github.com/gentleman-programming/tubemaster/blob/feature-2/openspec/changes/archive/2026-04-24-youtube-select-write-channel/verify-report.md

This test case verifies that selectWriteChannel persists the requested channel and returns the mismatch state. It is part of the cli-auth-bootstrap feature.

```typescript
src/lib/cli-auth/service.test.ts > selectWriteChannel persists requested channel and returns mismatch state
```

--------------------------------

### MCP Write Context Test Case

Source: https://github.com/gentleman-programming/tubemaster/blob/feature-2/openspec/changes/archive/2026-04-24-youtube-select-write-channel/verify-report.md

This test case verifies that the MCP write_context correctly returns the active write-channel contract. It is part of the playlist-management-mcp feature.

```typescript
src/mcp/server.test.ts > MCP write_context returns active write-channel contract
```

--------------------------------

### MCP List Uses Active Auth Context Test

Source: https://github.com/gentleman-programming/tubemaster/blob/feature-2/openspec/changes/archive/2026-04-23-cli-auth-bootstrap/verify-report.md

This test case verifies that the MCP 'list' command utilizes the active authentication context by default when no explicit `credentialRef` is provided.

```typescript
src/mcp/server.test.ts > MCP list uses active auth context when credentialRef is omitted
```

--------------------------------

### Write Channel Context Type Definition

Source: https://github.com/gentleman-programming/tubemaster/blob/feature-2/openspec/changes/archive/2026-04-23-youtube-write-channel-and-playlist-delete/design.md

Defines the structure for holding context related to write operations, including the active YouTube channel, the expected channel ID, and the source of the expected channel ID.

```typescript
type WriteChannelContext = {
  activeChannel: { id: string; title: string | null } | null;
  expectedChannelId: string | null;
  source: "explicit" | "stored" | "missing";
};
```

--------------------------------

### Rules API - Manage Rules

Source: https://github.com/gentleman-programming/tubemaster/blob/feature-2/docs/interfaces.md

Allows for the management of rules, including creation, retrieval, and deletion. Used by the Web UI.

```APIDOC
## GET|POST|DELETE /api/rules

### Description
Manages rules, allowing for retrieval (GET), creation (POST), and deletion (DELETE) of rules. This endpoint is used by the Web UI.

### Method
GET | POST | DELETE

### Endpoint
/api/rules

### Request Body (for POST/DELETE)
- **rule** (object) - Required for POST - The rule object to create or delete.
  - **field** (string) - Required - The field the rule applies to.
  - **matchType** (string) - Required - The type of match for the rule.
  - **targetPlaylist** (string) - Required - The target playlist for the rule.
- **ruleId** (string) - Required for DELETE - The ID of the rule to delete.

### Request Example (POST)
```json
{
  "rule": {
    "field": "title",
    "matchType": "contains",
    "targetPlaylist": "PL..."
  }
}
```

### Request Example (DELETE)
```json
{
  "ruleId": "RULE_ID"
}
```

### Response
#### Success Response (200)
- **rules** (array) - A list of rule objects (for GET).
- **message** (string) - A confirmation message (for POST/DELETE).

#### Response Example (GET)
```json
{
  "rules": [
    {
      "id": "RULE_ID",
      "field": "title",
      "matchType": "contains",
      "targetPlaylist": "PL..."
    }
  ]
}
```

#### Response Example (POST/DELETE)
```json
{
  "message": "Rule created successfully."
}
```
```

--------------------------------

### CLI Stable JSON and Typed Errors

Source: https://github.com/gentleman-programming/tubemaster/blob/feature-2/openspec/changes/archive/2026-04-23-cli-auth-bootstrap/verify-report.md

This note confirms the implementation of a stable JSON envelope for CLI commands using `serializeSuccess` and `serializeError`. It also mentions that tests cover invalid callbacks and the `AUTH_REFRESH_TOKEN_MISSING` error.

```typescript
serializeSuccess/serializeError
```

--------------------------------

### Typed Resolution Errors

Source: https://github.com/gentleman-programming/tubemaster/blob/feature-2/openspec/changes/archive/2026-04-23-cli-auth-bootstrap/verify-report.md

This note confirms that typed resolution errors, specifically `AUTH_USER_NOT_FOUND` and `AUTH_SCOPE_INSUFFICIENT`, are handled using codes defined in `src/lib/cli-auth/errors.ts` and `src/lib/video-metadata/adapters/google-auth.ts`.

```typescript
src/lib/cli-auth/errors.ts
```

```typescript
src/lib/video-metadata/adapters/google-auth.ts
```

--------------------------------

### Run Type Check

Source: https://github.com/gentleman-programming/tubemaster/blob/feature-2/openspec/changes/archive/2026-04-23-cli-auth-bootstrap/verify-report.md

Execute the TypeScript compiler to ensure type safety without emitting JavaScript files. This is part of the build and test execution phase.

```bash
npx tsc --noEmit
```

--------------------------------

### Assert Write Channel Mismatch Reauth Test Case

Source: https://github.com/gentleman-programming/tubemaster/blob/feature-2/openspec/changes/archive/2026-04-24-youtube-select-write-channel/verify-report.md

This test case asserts that assertWriteChannel fails with WRITE_CHANNEL_MISMATCH when the active and expected channels differ. It is part of the youtube-write-channel-guardrails feature.

```typescript
src/lib/write-context/service.test.ts > assertWriteChannel fails with WRITE_CHANNEL_MISMATCH when active and expected differ
```

--------------------------------

### MCP Write Channel Select Test Case

Source: https://github.com/gentleman-programming/tubemaster/blob/feature-2/openspec/changes/archive/2026-04-24-youtube-select-write-channel/verify-report.md

This test case ensures that the MCP write_channel_select rejects invalid payloads before persistence. It is part of the playlist-management-mcp feature.

```typescript
src/mcp/server.test.ts > MCP write_channel_select rejects invalid payload before persistence
```

--------------------------------

### Core Interfaces for Video Metadata

Source: https://github.com/gentleman-programming/tubemaster/blob/feature-2/openspec/changes/archive/2026-04-23-video-metadata-cli-mcp/design.md

Defines the essential types used across the video metadata system, including credential references, transcript result statuses, and metadata draft structures. Adapters must validate external input with Zod and return typed domain errors.

```typescript
type CredentialRef = { userId: string } | { accessToken: string; refreshToken?: string };
```

```typescript
type TranscriptResult =
  | { status: "available"; text: string; language?: string }
  | { status: "unavailable"; reason: "no-captions" | "not-accessible" }
  | { status: "unsupported"; reason: "provider-missing" };
```

```typescript
type MetadataDraft = { finalTitle: string; description: string; promptVersion: string };
```

--------------------------------

### Resolve Google Credentials Insufficient Scopes Test

Source: https://github.com/gentleman-programming/tubemaster/blob/feature-2/openspec/changes/archive/2026-04-23-cli-auth-bootstrap/verify-report.md

This test case verifies that the `resolveGoogleCredentials` function rejects credentials that have insufficient scopes.

```typescript
src/lib/video-metadata/adapters/google-auth.test.ts > resolveGoogleCredentials rejects credentials with insufficient scopes
```