Setup .devcontainers and AGENT configs

Mårten Åsberg committed on 2026-05-15 at 20:45

.agents/skills/playwright-cli/SKILL.md +371 -0

diff --git a/.agents/skills/playwright-cli/SKILL.md b/.agents/skills/playwright-cli/SKILL.md
new file mode 100644
index 0000000..da40d18
@@ -0,0 +1,371 @@
---
name: playwright-cli
description: Automate browser interactions, test web pages and work with Playwright tests.
allowed-tools: Bash(pnpm playwright-cli *)
---
# Browser Automation with playwright-cli
The `playwright-cli` is installed locally, meaning all commands must be prepended with pnpm like so: `pnpm playwright-cli`.
## Quick start
```bash
# open new browser
playwright-cli open
# navigate to a page
playwright-cli goto https://playwright.dev
# interact with the page using refs from the snapshot
playwright-cli click e15
playwright-cli type "page.click"
playwright-cli press Enter
# take a screenshot (rarely used, as snapshot is more common)
playwright-cli screenshot
# close the browser
playwright-cli close
```
## Commands
### Core
```bash
playwright-cli open
# open and navigate right away
playwright-cli open https://example.com/
playwright-cli goto https://playwright.dev
playwright-cli type "search query"
playwright-cli click e3
playwright-cli dblclick e7
# --submit presses Enter after filling the element
playwright-cli fill e5 "user@example.com"  --submit
playwright-cli drag e2 e8
# drop files or data onto an element (from outside the page)
playwright-cli drop e4 --path=./image.png
playwright-cli drop e4 --data="text/plain=hello world"
playwright-cli hover e4
playwright-cli select e9 "option-value"
playwright-cli upload ./document.pdf
playwright-cli check e12
playwright-cli uncheck e12
playwright-cli snapshot
playwright-cli eval "document.title"
playwright-cli eval "el => el.textContent" e5
# get element id, class, or any attribute not visible in the snapshot
playwright-cli eval "el => el.id" e5
playwright-cli eval "el => el.getAttribute('data-testid')" e5
playwright-cli dialog-accept
playwright-cli dialog-accept "confirmation text"
playwright-cli dialog-dismiss
playwright-cli resize 1920 1080
playwright-cli close
```
### Navigation
```bash
playwright-cli go-back
playwright-cli go-forward
playwright-cli reload
```
### Keyboard
```bash
playwright-cli press Enter
playwright-cli press ArrowDown
playwright-cli keydown Shift
playwright-cli keyup Shift
```
### Mouse
```bash
playwright-cli mousemove 150 300
playwright-cli mousedown
playwright-cli mousedown right
playwright-cli mouseup
playwright-cli mouseup right
playwright-cli mousewheel 0 100
```
### Save as
```bash
playwright-cli screenshot
playwright-cli screenshot e5
```
### Tabs
```bash
playwright-cli tab-list
playwright-cli tab-new
playwright-cli tab-new https://example.com/page
playwright-cli tab-close
playwright-cli tab-close 2
playwright-cli tab-select 0
```
### Storage
```bash
playwright-cli state-save
playwright-cli state-save auth.json
playwright-cli state-load auth.json
# Cookies
playwright-cli cookie-list
playwright-cli cookie-list --domain=example.com
playwright-cli cookie-get session_id
playwright-cli cookie-set session_id abc123
playwright-cli cookie-set session_id abc123 --domain=example.com --httpOnly --secure
playwright-cli cookie-delete session_id
playwright-cli cookie-clear
# LocalStorage
playwright-cli localstorage-list
playwright-cli localstorage-get theme
playwright-cli localstorage-set theme dark
playwright-cli localstorage-delete theme
playwright-cli localstorage-clear
# SessionStorage
playwright-cli sessionstorage-list
playwright-cli sessionstorage-get step
playwright-cli sessionstorage-set step 3
playwright-cli sessionstorage-delete step
playwright-cli sessionstorage-clear
```
### Network
```bash
playwright-cli route "**/*.jpg" --status=404
playwright-cli route "https://api.example.com/**" --body='{"mock": true}'
playwright-cli route-list
playwright-cli unroute "**/*.jpg"
playwright-cli unroute
```
### DevTools
```bash
playwright-cli console
playwright-cli console warning
playwright-cli requests
playwright-cli request 5
playwright-cli run-code "async page => await page.context().grantPermissions(['geolocation'])"
playwright-cli run-code --filename=script.js
playwright-cli tracing-start
playwright-cli tracing-stop
playwright-cli video-start video.webm
playwright-cli video-chapter "Chapter Title" --description="Details" --duration=2000
playwright-cli video-stop
# launch the dashboard for UI review / design feedback — user annotates the page, you receive the annotated screenshot, snapshot, and notes
playwright-cli show --annotate
# generate a Playwright locator for an element from its ref or selector
playwright-cli generate-locator e5 --raw
# show a persistent highlight overlay for an element, optionally with a custom style
playwright-cli highlight e5
playwright-cli highlight e5 --style="outline: 3px dashed red"
# hide a single element highlight, or all page highlights when no target is given
playwright-cli highlight e5 --hide
playwright-cli highlight --hide
```
## Raw output
The global `--raw` option strips page status, generated code, and snapshot sections from the output, returning only the result value. Use it to pipe command output into other tools. Commands that don't produce output return nothing.
```bash
playwright-cli --raw eval "JSON.stringify(performance.timing)" | jq '.loadEventEnd - .navigationStart'
playwright-cli --raw eval "JSON.stringify([...document.querySelectorAll('a')].map(a => a.href))" > links.json
playwright-cli --raw snapshot > before.yml
playwright-cli click e5
playwright-cli --raw snapshot > after.yml
diff before.yml after.yml
TOKEN=$(playwright-cli --raw cookie-get session_id)
playwright-cli --raw localstorage-get theme
```
For structured output wrapping every reply as JSON, pass --json
```bash
playwright-cli list --json
```
## Open parameters
```bash
# Use specific browser when creating session
playwright-cli open --browser=chrome
playwright-cli open --browser=firefox
playwright-cli open --browser=webkit
playwright-cli open --browser=msedge
# Use persistent profile (by default profile is in-memory)
playwright-cli open --persistent
# Use persistent profile with custom directory
playwright-cli open --profile=/path/to/profile
# Connect to browser via Playwright Extension
playwright-cli attach --extension=chrome
# Connect to a running Chrome or Edge by channel name
playwright-cli attach --cdp=chrome
playwright-cli attach --cdp=msedge
# Connect to a running browser via CDP endpoint
playwright-cli attach --cdp=http://localhost:9222
# Start with config file
playwright-cli open --config=my-config.json
# Close the browser
playwright-cli close
# Detach from an attached browser (leaves the external browser running)
playwright-cli -s=msedge detach
# Delete user data for the default session
playwright-cli delete-data
```
## Snapshots
After each command, playwright-cli provides a snapshot of the current browser state.
```bash
> playwright-cli goto https://example.com
### Page
- Page URL: https://example.com/
- Page Title: Example Domain
### Snapshot
[Snapshot](.playwright-cli/page-2026-02-14T19-22-42-679Z.yml)
```
You can also take a snapshot on demand using `playwright-cli snapshot` command. All the options below can be combined as needed.
```bash
# default - save to a file with timestamp-based name
playwright-cli snapshot
# save to file, use when snapshot is a part of the workflow result
playwright-cli snapshot --filename=after-click.yaml
# snapshot an element instead of the whole page
playwright-cli snapshot "#main"
# limit snapshot depth for efficiency, take a partial snapshot afterwards
playwright-cli snapshot --depth=4
playwright-cli snapshot e34
# include each element's bounding box as [box=x,y,width,height]
playwright-cli snapshot --boxes
```
## Targeting elements
By default, use refs from the snapshot to interact with page elements.
```bash
# get snapshot with refs
playwright-cli snapshot
# interact using a ref
playwright-cli click e15
```
You can also use css selectors or Playwright locators.
```bash
# css selector
playwright-cli click "#main > button.submit"
# role locator
playwright-cli click "getByRole('button', { name: 'Submit' })"
# test id
playwright-cli click "getByTestId('submit-button')"
```
## Browser Sessions
```bash
# create new browser session named "mysession" with persistent profile
playwright-cli -s=mysession open example.com --persistent
# same with manually specified profile directory (use when requested explicitly)
playwright-cli -s=mysession open example.com --profile=/path/to/profile
playwright-cli -s=mysession click e6
playwright-cli -s=mysession close  # stop a named browser
playwright-cli -s=mysession delete-data  # delete user data for persistent session
playwright-cli list
# Close all browsers
playwright-cli close-all
# Forcefully kill all browser processes
playwright-cli kill-all
```
## Example: Form submission
```bash
playwright-cli open https://example.com/form
playwright-cli snapshot
playwright-cli fill e1 "user@example.com"
playwright-cli fill e2 "password123"
playwright-cli click e3
playwright-cli snapshot
playwright-cli close
```
## Example: Multi-tab workflow
```bash
playwright-cli open https://example.com
playwright-cli tab-new https://example.com/other
playwright-cli tab-list
playwright-cli tab-select 0
playwright-cli snapshot
playwright-cli close
```
## Example: Debugging with DevTools
```bash
playwright-cli open https://example.com
playwright-cli click e4
playwright-cli fill e7 "test"
playwright-cli console
playwright-cli requests
playwright-cli close
```
```bash
playwright-cli open https://example.com
playwright-cli tracing-start
playwright-cli click e4
playwright-cli fill e7 "test"
playwright-cli tracing-stop
playwright-cli close
```
## Example: Interactive session
Ask the user for UI review or design feedback. The user draws boxes on the live page and types comments; you receive the annotated screenshot, the snapshot of the marked region, and the user's notes. Use this whenever the user asks for "UI review", "design feedback", or to "ask the user what they think / want / mean":
```bash
playwright-cli open https://example.com
playwright-cli show --annotate
```
## Specific tasks
* **Request mocking** [references/request-mocking.md](references/request-mocking.md)
* **Running Playwright code** [references/running-code.md](references/running-code.md)
* **Browser session management** [references/session-management.md](references/session-management.md)
* **Storage state (cookies, localStorage)** [references/storage-state.md](references/storage-state.md)
* **Tracing** [references/tracing.md](references/tracing.md)
* **Video recording** [references/video-recording.md](references/video-recording.md)
* **Inspecting element attributes** [references/element-attributes.md](references/element-attributes.md)

.agents/skills/playwright-cli/references/element-attributes.md +23 -0

diff --git a/.agents/skills/playwright-cli/references/element-attributes.md b/.agents/skills/playwright-cli/references/element-attributes.md
new file mode 100644
index 0000000..4e9fa6b
@@ -0,0 +1,23 @@
# Inspecting Element Attributes
When the snapshot doesn't show an element's `id`, `class`, `data-*` attributes, or other DOM properties, use `eval` to inspect them.
## Examples
```bash
playwright-cli snapshot
# snapshot shows a button as e7 but doesn't reveal its id or data attributes
# get the element's id
playwright-cli eval "el => el.id" e7
# get all CSS classes
playwright-cli eval "el => el.className" e7
# get a specific attribute
playwright-cli eval "el => el.getAttribute('data-testid')" e7
playwright-cli eval "el => el.getAttribute('aria-label')" e7
# get a computed style property
playwright-cli eval "el => getComputedStyle(el).display" e7
```

.agents/skills/playwright-cli/references/request-mocking.md +87 -0

diff --git a/.agents/skills/playwright-cli/references/request-mocking.md b/.agents/skills/playwright-cli/references/request-mocking.md
new file mode 100644
index 0000000..9005fda
@@ -0,0 +1,87 @@
# Request Mocking
Intercept, mock, modify, and block network requests.
## CLI Route Commands
```bash
# Mock with custom status
playwright-cli route "**/*.jpg" --status=404
# Mock with JSON body
playwright-cli route "**/api/users" --body='[{"id":1,"name":"Alice"}]' --content-type=application/json
# Mock with custom headers
playwright-cli route "**/api/data" --body='{"ok":true}' --header="X-Custom: value"
# Remove headers from requests
playwright-cli route "**/*" --remove-header=cookie,authorization
# List active routes
playwright-cli route-list
# Remove a route or all routes
playwright-cli unroute "**/*.jpg"
playwright-cli unroute
```
## URL Patterns
```
**/api/users           - Exact path match
**/api/*/details       - Wildcard in path
**/*.{png,jpg,jpeg}    - Match file extensions
**/search?q=*          - Match query parameters
```
## Advanced Mocking with run-code
For conditional responses, request body inspection, response modification, or delays:
### Conditional Response Based on Request
```bash
playwright-cli run-code "async page => {
  await page.route('**/api/login', route => {
    const body = route.request().postDataJSON();
    if (body.username === 'admin') {
      route.fulfill({ body: JSON.stringify({ token: 'mock-token' }) });
    } else {
      route.fulfill({ status: 401, body: JSON.stringify({ error: 'Invalid' }) });
    }
  });
}"
```
### Modify Real Response
```bash
playwright-cli run-code "async page => {
  await page.route('**/api/user', async route => {
    const response = await route.fetch();
    const json = await response.json();
    json.isPremium = true;
    await route.fulfill({ response, json });
  });
}"
```
### Simulate Network Failures
```bash
playwright-cli run-code "async page => {
  await page.route('**/api/offline', route => route.abort('internetdisconnected'));
}"
# Options: connectionrefused, timedout, connectionreset, internetdisconnected
```
### Delayed Response
```bash
playwright-cli run-code "async page => {
  await page.route('**/api/slow', async route => {
    await new Promise(r => setTimeout(r, 3000));
    route.fulfill({ body: JSON.stringify({ data: 'loaded' }) });
  });
}"
```

.agents/skills/playwright-cli/references/running-code.md +241 -0

diff --git a/.agents/skills/playwright-cli/references/running-code.md b/.agents/skills/playwright-cli/references/running-code.md
new file mode 100644
index 0000000..98b541f
@@ -0,0 +1,241 @@
# Running Custom Playwright Code
Use `run-code` to execute arbitrary Playwright code for advanced scenarios not covered by CLI commands.
## Syntax
```bash
playwright-cli run-code "async page => {
  // Your Playwright code here
  // Access page.context() for browser context operations
}"
```
You can also load the function from a file:
```bash
playwright-cli run-code --filename=./my-script.js
```
The code must be a single function expression, it is wrapped in `(...)` and evaluated.
import/export/require syntax is not supported.
## Geolocation
```bash
# Grant geolocation permission and set location
playwright-cli run-code "async page => {
  await page.context().grantPermissions(['geolocation']);
  await page.context().setGeolocation({ latitude: 37.7749, longitude: -122.4194 });
}"
# Set location to London
playwright-cli run-code "async page => {
  await page.context().grantPermissions(['geolocation']);
  await page.context().setGeolocation({ latitude: 51.5074, longitude: -0.1278 });
}"
# Clear geolocation override
playwright-cli run-code "async page => {
  await page.context().clearPermissions();
}"
```
## Permissions
```bash
# Grant multiple permissions
playwright-cli run-code "async page => {
  await page.context().grantPermissions([
    'geolocation',
    'notifications',
    'camera',
    'microphone'
  ]);
}"
# Grant permissions for specific origin
playwright-cli run-code "async page => {
  await page.context().grantPermissions(['clipboard-read'], {
    origin: 'https://example.com'
  });
}"
```
## Media Emulation
```bash
# Emulate dark color scheme
playwright-cli run-code "async page => {
  await page.emulateMedia({ colorScheme: 'dark' });
}"
# Emulate light color scheme
playwright-cli run-code "async page => {
  await page.emulateMedia({ colorScheme: 'light' });
}"
# Emulate reduced motion
playwright-cli run-code "async page => {
  await page.emulateMedia({ reducedMotion: 'reduce' });
}"
# Emulate print media
playwright-cli run-code "async page => {
  await page.emulateMedia({ media: 'print' });
}"
```
## Wait Strategies
```bash
# Wait for network idle
playwright-cli run-code "async page => {
  await page.waitForLoadState('networkidle');
}"
# Wait for specific element
playwright-cli run-code "async page => {
  await page.locator('.loading').waitFor({ state: 'hidden' });
}"
# Wait for function to return true
playwright-cli run-code "async page => {
  await page.waitForFunction(() => window.appReady === true);
}"
# Wait with timeout
playwright-cli run-code "async page => {
  await page.locator('.result').waitFor({ timeout: 10000 });
}"
```
## Frames and Iframes
```bash
# Work with iframe
playwright-cli run-code "async page => {
  const frame = page.locator('iframe#my-iframe').contentFrame();
  await frame.locator('button').click();
}"
# Get all frames
playwright-cli run-code "async page => {
  const frames = page.frames();
  return frames.map(f => f.url());
}"
```
## File Downloads
```bash
# Handle file download
playwright-cli run-code "async page => {
  const downloadPromise = page.waitForEvent('download');
  await page.getByRole('link', { name: 'Download' }).click();
  const download = await downloadPromise;
  await download.saveAs('./downloaded-file.pdf');
  return download.suggestedFilename();
}"
```
## Clipboard
```bash
# Read clipboard (requires permission)
playwright-cli run-code "async page => {
  await page.context().grantPermissions(['clipboard-read']);
  return await page.evaluate(() => navigator.clipboard.readText());
}"
# Write to clipboard
playwright-cli run-code "async page => {
  await page.evaluate(text => navigator.clipboard.writeText(text), 'Hello clipboard!');
}"
```
## Page Information
```bash
# Get page title
playwright-cli run-code "async page => {
  return await page.title();
}"
# Get current URL
playwright-cli run-code "async page => {
  return page.url();
}"
# Get page content
playwright-cli run-code "async page => {
  return await page.content();
}"
# Get viewport size
playwright-cli run-code "async page => {
  return page.viewportSize();
}"
```
## JavaScript Execution
```bash
# Execute JavaScript and return result
playwright-cli run-code "async page => {
  return await page.evaluate(() => {
    return {
      userAgent: navigator.userAgent,
      language: navigator.language,
      cookiesEnabled: navigator.cookieEnabled
    };
  });
}"
# Pass arguments to evaluate
playwright-cli run-code "async page => {
  const multiplier = 5;
  return await page.evaluate(m => document.querySelectorAll('li').length * m, multiplier);
}"
```
## Error Handling
```bash
# Try-catch in run-code
playwright-cli run-code "async page => {
  try {
    await page.getByRole('button', { name: 'Submit' }).click({ timeout: 1000 });
    return 'clicked';
  } catch (e) {
    return 'element not found';
  }
}"
```
## Complex Workflows
```bash
# Login and save state
playwright-cli run-code "async page => {
  await page.goto('https://example.com/login');
  await page.getByRole('textbox', { name: 'Email' }).fill('user@example.com');
  await page.getByRole('textbox', { name: 'Password' }).fill('secret');
  await page.getByRole('button', { name: 'Sign in' }).click();
  await page.waitForURL('**/dashboard');
  await page.context().storageState({ path: 'auth.json' });
  return 'Login successful';
}"
# Scrape data from multiple pages
playwright-cli run-code "async page => {
  const results = [];
  for (let i = 1; i <= 3; i++) {
    await page.goto(\`https://example.com/page/\${i}\`);
    const items = await page.locator('.item').allTextContents();
    results.push(...items);
  }
  return results;
}"
```

.agents/skills/playwright-cli/references/session-management.md +225 -0

diff --git a/.agents/skills/playwright-cli/references/session-management.md b/.agents/skills/playwright-cli/references/session-management.md
new file mode 100644
index 0000000..bf39acd
@@ -0,0 +1,225 @@
# Browser Session Management
Run multiple isolated browser sessions concurrently with state persistence.
## Named Browser Sessions
Use `-s` flag to isolate browser contexts:
```bash
# Browser 1: Authentication flow
playwright-cli -s=auth open https://app.example.com/login
# Browser 2: Public browsing (separate cookies, storage)
playwright-cli -s=public open https://example.com
# Commands are isolated by browser session
playwright-cli -s=auth fill e1 "user@example.com"
playwright-cli -s=public snapshot
```
## Browser Session Isolation Properties
Each browser session has independent:
- Cookies
- LocalStorage / SessionStorage
- IndexedDB
- Cache
- Browsing history
- Open tabs
## Browser Session Commands
```bash
# List all browser sessions
playwright-cli list
# Stop a browser session (close the browser)
playwright-cli close                # stop the default browser
playwright-cli -s=mysession close   # stop a named browser
# Stop all browser sessions
playwright-cli close-all
# Forcefully kill all daemon processes (for stale/zombie processes)
playwright-cli kill-all
# Delete browser session user data (profile directory)
playwright-cli delete-data                # delete default browser data
playwright-cli -s=mysession delete-data   # delete named browser data
```
## Environment Variable
Set a default browser session name via environment variable:
```bash
export PLAYWRIGHT_CLI_SESSION="mysession"
playwright-cli open example.com  # Uses "mysession" automatically
```
## Common Patterns
### Concurrent Scraping
```bash
#!/bin/bash
# Scrape multiple sites concurrently
# Start all browsers
playwright-cli -s=site1 open https://site1.com &
playwright-cli -s=site2 open https://site2.com &
playwright-cli -s=site3 open https://site3.com &
wait
# Take snapshots from each
playwright-cli -s=site1 snapshot
playwright-cli -s=site2 snapshot
playwright-cli -s=site3 snapshot
# Cleanup
playwright-cli close-all
```
### A/B Testing Sessions
```bash
# Test different user experiences
playwright-cli -s=variant-a open "https://app.com?variant=a"
playwright-cli -s=variant-b open "https://app.com?variant=b"
# Compare
playwright-cli -s=variant-a screenshot
playwright-cli -s=variant-b screenshot
```
### Persistent Profile
By default, browser profile is kept in memory only. Use `--persistent` flag on `open` to persist the browser profile to disk:
```bash
# Use persistent profile (auto-generated location)
playwright-cli open https://example.com --persistent
# Use persistent profile with custom directory
playwright-cli open https://example.com --profile=/path/to/profile
```
## Attaching to a Running Browser
Use `attach` to connect to a browser that is already running, instead of launching a new one.
### Attach by channel name
Connect to a running Chrome or Edge instance by its channel name. The browser must have remote debugging enabled — navigate to `chrome://inspect/#remote-debugging` in the target browser and check "Allow remote debugging for this browser instance".
```bash
# Attach to Chrome
playwright-cli attach --cdp=chrome
# Attach to Chrome Canary
playwright-cli attach --cdp=chrome-canary
# Attach to Microsoft Edge
playwright-cli attach --cdp=msedge
# Attach to Edge Dev
playwright-cli attach --cdp=msedge-dev
```
Supported channels: `chrome`, `chrome-beta`, `chrome-dev`, `chrome-canary`, `msedge`, `msedge-beta`, `msedge-dev`, `msedge-canary`.
When `--session` is not provided, the session is named after the channel (e.g. `--cdp=msedge` creates a session called `msedge`), so parallel attaches to Chrome and Edge don't collide on `default`. Pass `--session=<name>` to override.
### Attach via CDP endpoint
Connect to a browser that exposes a Chrome DevTools Protocol endpoint:
```bash
playwright-cli attach --cdp=http://localhost:9222
```
### Attach via browser extension
Connect to a browser with the Playwright extension installed:
```bash
playwright-cli attach --extension
```
### Detach
Tear down an attached session without affecting the external browser:
```bash
# Detach the default attached session
playwright-cli detach
# Detach a specific attached session
playwright-cli -s=msedge detach
```
`detach` only works on sessions created via `attach`. For sessions created via `open`, use `close`.
## Default Browser Session
When `-s` is omitted, commands use the default browser session:
```bash
# These use the same default browser session
playwright-cli open https://example.com
playwright-cli snapshot
playwright-cli close  # Stops default browser
```
## Browser Session Configuration
Configure a browser session with specific settings when opening:
```bash
# Open with config file
playwright-cli open https://example.com --config=.playwright/my-cli.json
# Open with specific browser
playwright-cli open https://example.com --browser=firefox
# Open in headed mode
playwright-cli open https://example.com --headed
# Open with persistent profile
playwright-cli open https://example.com --persistent
```
## Best Practices
### 1. Name Browser Sessions Semantically
```bash
# GOOD: Clear purpose
playwright-cli -s=github-auth open https://github.com
playwright-cli -s=docs-scrape open https://docs.example.com
# AVOID: Generic names
playwright-cli -s=s1 open https://github.com
```
### 2. Always Clean Up
```bash
# Stop browsers when done
playwright-cli -s=auth close
playwright-cli -s=scrape close
# Or stop all at once
playwright-cli close-all
# If browsers become unresponsive or zombie processes remain
playwright-cli kill-all
```
### 3. Delete Stale Browser Data
```bash
# Remove old browser data to free disk space
playwright-cli -s=oldsession delete-data
```

.agents/skills/playwright-cli/references/storage-state.md +275 -0

diff --git a/.agents/skills/playwright-cli/references/storage-state.md b/.agents/skills/playwright-cli/references/storage-state.md
new file mode 100644
index 0000000..c856db5
@@ -0,0 +1,275 @@
# Storage Management
Manage cookies, localStorage, sessionStorage, and browser storage state.
## Storage State
Save and restore complete browser state including cookies and storage.
### Save Storage State
```bash
# Save to auto-generated filename (storage-state-{timestamp}.json)
playwright-cli state-save
# Save to specific filename
playwright-cli state-save my-auth-state.json
```
### Restore Storage State
```bash
# Load storage state from file
playwright-cli state-load my-auth-state.json
# Reload page to apply cookies
playwright-cli open https://example.com
```
### Storage State File Format
The saved file contains:
```json
{
  "cookies": [
    {
      "name": "session_id",
      "value": "abc123",
      "domain": "example.com",
      "path": "/",
      "expires": 1735689600,
      "httpOnly": true,
      "secure": true,
      "sameSite": "Lax"
    }
  ],
  "origins": [
    {
      "origin": "https://example.com",
      "localStorage": [
        { "name": "theme", "value": "dark" },
        { "name": "user_id", "value": "12345" }
      ]
    }
  ]
}
```
## Cookies
### List All Cookies
```bash
playwright-cli cookie-list
```
### Filter Cookies by Domain
```bash
playwright-cli cookie-list --domain=example.com
```
### Filter Cookies by Path
```bash
playwright-cli cookie-list --path=/api
```
### Get Specific Cookie
```bash
playwright-cli cookie-get session_id
```
### Set a Cookie
```bash
# Basic cookie
playwright-cli cookie-set session abc123
# Cookie with options
playwright-cli cookie-set session abc123 --domain=example.com --path=/ --httpOnly --secure --sameSite=Lax
# Cookie with expiration (Unix timestamp)
playwright-cli cookie-set remember_me token123 --expires=1735689600
```
### Delete a Cookie
```bash
playwright-cli cookie-delete session_id
```
### Clear All Cookies
```bash
playwright-cli cookie-clear
```
### Advanced: Multiple Cookies or Custom Options
For complex scenarios like adding multiple cookies at once, use `run-code`:
```bash
playwright-cli run-code "async page => {
  await page.context().addCookies([
    { name: 'session_id', value: 'sess_abc123', domain: 'example.com', path: '/', httpOnly: true },
    { name: 'preferences', value: JSON.stringify({ theme: 'dark' }), domain: 'example.com', path: '/' }
  ]);
}"
```
## Local Storage
### List All localStorage Items
```bash
playwright-cli localstorage-list
```
### Get Single Value
```bash
playwright-cli localstorage-get token
```
### Set Value
```bash
playwright-cli localstorage-set theme dark
```
### Set JSON Value
```bash
playwright-cli localstorage-set user_settings '{"theme":"dark","language":"en"}'
```
### Delete Single Item
```bash
playwright-cli localstorage-delete token
```
### Clear All localStorage
```bash
playwright-cli localstorage-clear
```
### Advanced: Multiple Operations
For complex scenarios like setting multiple values at once, use `run-code`:
```bash
playwright-cli run-code "async page => {
  await page.evaluate(() => {
    localStorage.setItem('token', 'jwt_abc123');
    localStorage.setItem('user_id', '12345');
    localStorage.setItem('expires_at', Date.now() + 3600000);
  });
}"
```
## Session Storage
### List All sessionStorage Items
```bash
playwright-cli sessionstorage-list
```
### Get Single Value
```bash
playwright-cli sessionstorage-get form_data
```
### Set Value
```bash
playwright-cli sessionstorage-set step 3
```
### Delete Single Item
```bash
playwright-cli sessionstorage-delete step
```
### Clear sessionStorage
```bash
playwright-cli sessionstorage-clear
```
## IndexedDB
### List Databases
```bash
playwright-cli run-code "async page => {
  return await page.evaluate(async () => {
    const databases = await indexedDB.databases();
    return databases;
  });
}"
```
### Delete Database
```bash
playwright-cli run-code "async page => {
  await page.evaluate(() => {
    indexedDB.deleteDatabase('myDatabase');
  });
}"
```
## Common Patterns
### Authentication State Reuse
```bash
# Step 1: Login and save state
playwright-cli open https://app.example.com/login
playwright-cli snapshot
playwright-cli fill e1 "user@example.com"
playwright-cli fill e2 "password123"
playwright-cli click e3
# Save the authenticated state
playwright-cli state-save auth.json
# Step 2: Later, restore state and skip login
playwright-cli state-load auth.json
playwright-cli open https://app.example.com/dashboard
# Already logged in!
```
### Save and Restore Roundtrip
```bash
# Set up authentication state
playwright-cli open https://example.com
playwright-cli eval "() => { document.cookie = 'session=abc123'; localStorage.setItem('user', 'john'); }"
# Save state to file
playwright-cli state-save my-session.json
# ... later, in a new session ...
# Restore state
playwright-cli state-load my-session.json
playwright-cli open https://example.com
# Cookies and localStorage are restored!
```
## Security Notes
- Never commit storage state files containing auth tokens
- Add `*.auth-state.json` to `.gitignore`
- Delete state files after automation completes
- Use environment variables for sensitive data
- By default, sessions run in-memory mode which is safer for sensitive operations

.agents/skills/playwright-cli/references/tracing.md +139 -0

diff --git a/.agents/skills/playwright-cli/references/tracing.md b/.agents/skills/playwright-cli/references/tracing.md
new file mode 100644
index 0000000..7ce7bab
@@ -0,0 +1,139 @@
# Tracing
Capture detailed execution traces for debugging and analysis. Traces include DOM snapshots, screenshots, network activity, and console logs.
## Basic Usage
```bash
# Start trace recording
playwright-cli tracing-start
# Perform actions
playwright-cli open https://example.com
playwright-cli click e1
playwright-cli fill e2 "test"
# Stop trace recording
playwright-cli tracing-stop
```
## Trace Output Files
When you start tracing, Playwright creates a `traces/` directory with several files:
### `trace-{timestamp}.trace`
**Action log** - The main trace file containing:
- Every action performed (clicks, fills, navigations)
- DOM snapshots before and after each action
- Screenshots at each step
- Timing information
- Console messages
- Source locations
### `trace-{timestamp}.network`
**Network log** - Complete network activity:
- All HTTP requests and responses
- Request headers and bodies
- Response headers and bodies
- Timing (DNS, connect, TLS, TTFB, download)
- Resource sizes
- Failed requests and errors
### `resources/`
**Resources directory** - Cached resources:
- Images, fonts, stylesheets, scripts
- Response bodies for replay
- Assets needed to reconstruct page state
## What Traces Capture
| Category | Details |
|----------|---------|
| **Actions** | Clicks, fills, hovers, keyboard input, navigations |
| **DOM** | Full DOM snapshot before/after each action |
| **Screenshots** | Visual state at each step |
| **Network** | All requests, responses, headers, bodies, timing |
| **Console** | All console.log, warn, error messages |
| **Timing** | Precise timing for each operation |
## Use Cases
### Debugging Failed Actions
```bash
playwright-cli tracing-start
playwright-cli open https://app.example.com
# This click fails - why?
playwright-cli click e5
playwright-cli tracing-stop
# Open trace to see DOM state when click was attempted
```
### Analyzing Performance
```bash
playwright-cli tracing-start
playwright-cli open https://slow-site.com
playwright-cli tracing-stop
# View network waterfall to identify slow resources
```
### Capturing Evidence
```bash
# Record a complete user flow for documentation
playwright-cli tracing-start
playwright-cli open https://app.example.com/checkout
playwright-cli fill e1 "4111111111111111"
playwright-cli fill e2 "12/25"
playwright-cli fill e3 "123"
playwright-cli click e4
playwright-cli tracing-stop
# Trace shows exact sequence of events
```
## Trace vs Video vs Screenshot
| Feature | Trace | Video | Screenshot |
|---------|-------|-------|------------|
| **Format** | .trace file | .webm video | .png/.jpeg image |
| **DOM inspection** | Yes | No | No |
| **Network details** | Yes | No | No |
| **Step-by-step replay** | Yes | Continuous | Single frame |
| **File size** | Medium | Large | Small |
| **Best for** | Debugging | Demos | Quick capture |
## Best Practices
### 1. Start Tracing Before the Problem
```bash
# Trace the entire flow, not just the failing step
playwright-cli tracing-start
playwright-cli open https://example.com
# ... all steps leading to the issue ...
playwright-cli tracing-stop
```
### 2. Clean Up Old Traces
Traces can consume significant disk space:
```bash
# Remove traces older than 7 days
find .playwright-cli/traces -mtime +7 -delete
```
## Limitations
- Traces add overhead to automation
- Large traces can consume significant disk space
- Some dynamic content may not replay perfectly

.agents/skills/playwright-cli/references/video-recording.md +143 -0

diff --git a/.agents/skills/playwright-cli/references/video-recording.md b/.agents/skills/playwright-cli/references/video-recording.md
new file mode 100644
index 0000000..ce9ad6a
@@ -0,0 +1,143 @@
# Video Recording
Capture browser automation sessions as video for debugging, documentation, or verification. Produces WebM (VP8/VP9 codec).
## Basic Recording
```bash
# Open browser first
playwright-cli open
# Start recording
playwright-cli video-start demo.webm
# Add a chapter marker for section transitions
playwright-cli video-chapter "Getting Started" --description="Opening the homepage" --duration=2000
# Navigate and perform actions
playwright-cli goto https://example.com
playwright-cli snapshot
playwright-cli click e1
# Add another chapter
playwright-cli video-chapter "Filling Form" --description="Entering test data" --duration=2000
playwright-cli fill e2 "test input"
# Stop and save
playwright-cli video-stop
```
## Best Practices
### 1. Use Descriptive Filenames
```bash
# Include context in filename
playwright-cli video-start recordings/login-flow-2024-01-15.webm
playwright-cli video-start recordings/checkout-test-run-42.webm
```
### 2. Record entire hero scripts.
When recording a video for the user or as a proof of work, it is best to create a code snippet and execute it with run-code.
It allows pulling appropriate pauses between the actions and annotating the video. There are new Playwright APIs for that.
1) Perform scenario using CLI and take note of all locators and actions. You'll need those locators to request their bounding boxes for highlight.
2) Create a file with the intended script for video (below). Use pressSequentially w/ delay for nice typing, make reasonable pauses.
3) Use playwright-cli run-code --filename your-script.js
**Important**: Overlays are `pointer-events: none` — they do not interfere with page interactions. You can safely keep sticky overlays visible while clicking, filling, or performing any actions on the page.
```js
async page => {
  await page.screencast.start({ path: 'video.webm', size: { width: 1280, height: 800 } });
  await page.goto('https://demo.playwright.dev/todomvc');
  // Show a chapter card — blurs the page and shows a dialog.
  // Blocks until duration expires, then auto-removes.
  // Use this for simple use cases, but always feel free to hand-craft your own beautiful
  // overlay via await page.screencast.showOverlay().
  await page.screencast.showChapter('Adding Todo Items', {
    description: 'We will add several items to the todo list.',
    duration: 2000,
  });
  // Perform action
  await page.getByRole('textbox', { name: 'What needs to be done?' }).pressSequentially('Walk the dog', { delay: 60 });
  await page.getByRole('textbox', { name: 'What needs to be done?' }).press('Enter');
  await page.waitForTimeout(1000);
  // Show next chapter
  await page.screencast.showChapter('Verifying Results', {
    description: 'Checking the item appeared in the list.',
    duration: 2000,
  });
  // Add a sticky annotation that stays while you perform actions.
  // Overlays are pointer-events: none, so they won't block clicks.
  const annotation = await page.screencast.showOverlay(`
    <div style="position: absolute; top: 8px; right: 8px;
      padding: 6px 12px; background: rgba(0,0,0,0.7);
      border-radius: 8px; font-size: 13px; color: white;">
      ✓ Item added successfully
    </div>
  `);
  // Perform more actions while the annotation is visible
  await page.getByRole('textbox', { name: 'What needs to be done?' }).pressSequentially('Buy groceries', { delay: 60 });
  await page.getByRole('textbox', { name: 'What needs to be done?' }).press('Enter');
  await page.waitForTimeout(1500);
  // Remove the annotation when done
  await annotation.dispose();
  // You can also highlight relevant locators and provide contextual annotations.
  const bounds = await page.getByText('Walk the dog').boundingBox();
  await page.screencast.showOverlay(`
    <div style="position: absolute;
      top: ${bounds.y}px;
      left: ${bounds.x}px;
      width: ${bounds.width}px;
      height: ${bounds.height}px;
      border: 1px solid red;">
    </div>
    <div style="position: absolute;
      top: ${bounds.y + bounds.height + 5}px;
      left: ${bounds.x + bounds.width / 2}px;
      transform: translateX(-50%);
      padding: 6px;
      background: #808080;
      border-radius: 10px;
      font-size: 14px;
      color: white;">Check it out, it is right above this text
    </div>
  `, { duration: 2000 });
  await page.screencast.stop();
}
```
Embrace creativity, overlays are powerful.
### Overlay API Summary
| Method | Use Case |
|--------|----------|
| `page.screencast.showChapter(title, { description?, duration?, styleSheet? })` | Full-screen chapter card with blurred backdrop — ideal for section transitions |
| `page.screencast.showOverlay(html, { duration? })` | Custom HTML overlay — use for callouts, labels, highlights |
| `disposable.dispose()` | Remove a sticky overlay added without duration |
| `page.screencast.hideOverlays()` / `page.screencast.showOverlays()` | Temporarily hide/show all overlays |
## Tracing vs Video
| Feature | Video | Tracing |
|---------|-------|---------|
| Output | WebM file | Trace file (viewable in Trace Viewer) |
| Shows | Visual recording | DOM snapshots, network, console, actions |
| Use case | Demos, documentation | Debugging, analysis |
| Size | Larger | Smaller |
## Limitations
- Recording adds slight overhead to automation
- Large recordings can consume significant disk space

.devcontainer/dev.containerfile +36 -0

diff --git a/.devcontainer/dev.containerfile b/.devcontainer/dev.containerfile
new file mode 100644
index 0000000..ce36506
@@ -0,0 +1,36 @@
FROM mcr.microsoft.com/dotnet/sdk:11.0.100-preview.2
RUN apt-get update && apt-get install \
  xz-utils \
  gpg \
  ca-certificates \
  -y
# Install ffmpeg
RUN apt-get install -y ffmpeg
# Install sqlite3
RUN apt-get install -y sqlite3
# Install node/npm
ENV NODE_VERSION 26.1.0
RUN ARCH= && dpkgArch="`$(dpkg --print-architecture)" \
  && case "`${dpkgArch##*-}" in \
    amd64) ARCH='x64';; \
    ppc64el) ARCH='ppc64le';; \
    s390x) ARCH='s390x';; \
    arm64) ARCH='arm64';; \
    armhf) ARCH='armv7l';; \
    i386) ARCH='x86';; \
    *) echo "unsupported architecture"; exit 1 ;; \
  esac \
  && curl -fsSLO --compressed "https://nodejs.org/dist/v`$NODE_VERSION/node-v`$NODE_VERSION-linux-`$ARCH.tar.xz" \
  && tar -xJf "node-v`$NODE_VERSION-linux-`$ARCH.tar.xz" -C /usr/local --strip-components=1 --no-same-owner \
  && rm "node-v`$NODE_VERSION-linux-`$ARCH.tar.xz" \
  && ln -s /usr/local/bin/node /usr/local/bin/nodejs
RUN npm install -g corepack@latest
# Install chromium
RUN curl -fsSL https://dl.google.com/linux/linux_signing_key.pub | gpg --dearmor --yes -o /usr/share/keyrings/chrome.gpg
RUN echo 'deb [arch=amd64 signed-by=/usr/share/keyrings/chrome.gpg] http://dl.google.com/linux/chrome/deb/ stable main' > /etc/apt/sources.list.d/google-chrome.list
RUN apt-get update && apt-get install -y google-chrome-stable

.devcontainer/devcontainer.json +11 -0

diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json
new file mode 100644
index 0000000..ccfbd4b
@@ -0,0 +1,11 @@
{
  "name": "Slopper DEV",
  "build": {
    "dockerfile": "dev.containerfile"
  },
  "postCreateCommand": {
    "pnpm setup": "corepack install && pnpm ci",
    "dotnet setup": "dotnet restore --locked-mode",
    "dotnet tools": "dotnet tool restore"
  }
}

.gitignore +4 -1

diff --git a/.gitignore b/.gitignore
index 2042773..2665a82 100644
@@ -38,7 +38,7 @@ bld/
# Visual Studio 2015/2017 cache/options directory
.vs/
# Uncomment if you have tasks that create the project's static files in wwwroot
#wwwroot/
wwwroot/
# Visual Studio 2017 auto generated files
Generated\ Files/
@@ -485,3 +485,6 @@ $RECYCLE.BIN/
# Development files
*.db*
# Playwright
.playwright-cli

.playwright/cli.config.json +15 -0

diff --git a/.playwright/cli.config.json b/.playwright/cli.config.json
new file mode 100644
index 0000000..2671685
@@ -0,0 +1,15 @@
{
  "browser": {
    "launchOptions": {
      "headless": true
    },
    "contextOptions": {
      "viewport": {
        "width": 411,
        "height": 892
      },
      "userAgent": "Mozilla/5.0 (Linux; Android 10; K) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/148.0.0.0 Mobile Safari/537.36 EdgA/148.0.0.0"
    }
  },
  "codegen": "none"
}

AGENTS.md +127 -0

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..e33d632
@@ -0,0 +1,127 @@
# Slopper — Agent Guide
Slopper picks a random piece of media from a Jellyfin database, uses AI to find a clippable moment, cuts it with FFmpeg, and stores the clip. Clips are viewable on the web frontend and can be uploaded to short-form platforms.
## Project Structure
```
src/
  Api/            # ASP.NET Core REST API (port 5055)
  Cli/            # .NET console app — primary local experimentation tool
  Domain/         # Core domain models and abstractions
  Frontend/       # Vue 3 + TypeScript SPA (Vite)
  Infrastructure/
    Ai/           # Ollama integration
    Database/     # EF Core / SQLite
    Ffmpeg/       # FFmpeg media processing
    YouTube/      # YouTube API integration
```
## Build Commands
```sh
# .NET
dotnet build
# Frontend
pnpm -C src/Frontend build
```
## Running Services
```sh
# API
dotnet run --project src/Api/Api.csproj
# Frontend dev server (port printed on start)
pnpm -C src/Frontend dev
# CLI (experimentation)
dotnet run --project src/Cli/Cli.csproj
```
For full E2E testing, build the frontend into the API's static files directory:
```sh
pnpm -C src/Frontend build --emptyOutDir --outDir ../Api/wwwroot/
dotnet run --project src/Api/Api.csproj
```
## Database Migrations
```sh
dotnet ef migrations add <MigrationName> --project src/Infrastructure/Database
```
Migrations run automatically on startup of `Api` and `Cli`.
## Key Notes for Agents
### Project layout & build
- `Domain` and `Infrastructure` are pure class libraries — no entry point, built implicitly by `Api`/`Cli`.
- `Cli/Program.cs` is the experimentation scratchpad. Edit it freely; checked-in experiments are welcome.
- The project targets .NET 11 (preview SDK — `global.json` pins the exact version).
- The pnpm workspace root is at the repo root; the only workspace member is `src/Frontend`.
- Never manually edit `*.csproj`, `package.json`, or `pnpm-lock.yaml`. Use `dotnet add package` and `pnpm add` so lock files stay consistent.
### Architecture & DI patterns
- Service registration lives in `extension()` blocks — a C# 14 syntax. Each Infrastructure project has a `ServiceCollectionExtensions` file with `AddXxx()` extension methods.
- All options classes are validated at startup via `[OptionsValidator]`-generated validators and `ValidateOnStart()`. Missing or malformed config will crash the host immediately, not lazily.
- `Cli` and `Api` share the same secrets schema but have different User Secrets IDs. The `Cli` omits Quartz, web middleware, and authentication — it's a plain `IHost`.
- `Api` and `Cli` both run `SlopperStartupMigration` (a `IHostedService`) on startup, which applies any pending EF migrations automatically.
### API surface
- All routes are under `/api`.
- `GET /api/clips` — paginated, cursor-based via `after` (Guid). Max `limit` is 64.
- `GET /api/clips/{id}/stream` — returns `video/mp4` with range request support (seekable).
- `GET/PUT /api/jobs` — gets job status / manually triggers `ClipGenerationJob`.
- `GET/PUT /api/youtube/upload` — YouTube upload job status / trigger. Require Google authentication.
- YouTube OAuth callback lands at `/admin/redirect/youtube`. The frontend admin page is at `/admin/youtube`.
### Background jobs (Quartz)
- Three Quartz jobs: `ClipGenerationJob`, `CleanupJob`, `UploadJob`.
- `ClipGenerationJob`: `[DisallowConcurrentExecution]`. In Production it fires immediately on startup; in Development it only fires when manually triggered via `PUT /api/jobs`. If `ClipGenerationJob.Interval` is set (nullable `TimeSpan?`), the job reschedules itself after each run, it is not set in Development.
- `CleanupJob`: runs on cron `"0 0 * * * ?"` (top of every hour). Marks old clips as removed and deletes files from disk.
- `UploadJob`: resolves `IUploader` keyed by platform name from `context.MergedJobDataMap` — currently only `"YouTube"` is registered.
### Domain model
- `Clip` is a sealed record. `Tags` is `IReadOnlySet<Tag>` and is init-only. `Uploads` is a mutable collection appended to when a clip is uploaded.
- `Tag` and `Upload` are sealed records (value objects). `Upload.CanonicalUrl` is a `Uri` stored as a string in SQLite.
- `ClipSelector` is a singleton — it holds a pre-computed embedding of the configured `ClippableQuotes` and uses cosine similarity to pick the best subtitle moment.
- `ClipGenerator` is transient. It orchestrates: select media → extract subtitles → find clippable moment → extract clip → extract frame → generate AI description → save.
### Database
- Two separate SQLite files: Jellyfin (read-only, external schema) and Slopper (R/W, owned schema).
- Jellyfin uses `JellyfinDbContext` from the `Jellyfin.Database.Implementations` NuGet package — do not modify its schema or migrations.
- `IClipRepository` is registered as transient. Key query methods: `GetLatest` (cursor paginated), `GetCreatedBefore` (for cleanup), `GetNotUploadedTo` (for upload scheduling).
- EF migrations live in `src/Infrastructure/Database`. Always pass `--project src/Infrastructure/Database` when running `dotnet ef`.
### Infrastructure details
- **Ffmpeg**: `IClipExtractor`, `ISubtitleReader`, `IFrameExtractor` — all transient, all use a memory cache. Relies on FFMpegCore and SubtitlesParserV2.
- **Ai**: Ollama HTTP client with a 10-minute timeout. Both `IChatClient` and `IEmbeddingGenerator<string, Embedding<float>>` are registered and decorated with OpenTelemetry.
- **YouTube**: `YouTubeUploader` registers clips as `PrivacyStatus="private"` with a future `PublishAt` time controlled by `Uploader.PublishInterval`. Videos are categorized as `CategoryId="1"` (Film & Animation).
### Frontend
- Vue 3 + TypeScript; router has two routes: `/` (`ClipFeed`) and `/admin/youtube` (`AdminYouTubePage`).
- API client is `src/services/api.ts` — plain `fetch`, handles 403 as unauthenticated.
- Build script runs `vue-tsc -b && vite build` (type-checks before bundling). A type error will fail the build.
- The Vite dev server has no proxy config — in dev, the frontend expects the API to be running separately on port 5055.
- Use Playwright to confirm the UI looks as it should, or ask the user for feedback.
### Observability
- Both `Api` and `Cli` configure OpenTelemetry with OTLP export. Instrumented: ASP.NET Core (Api only), EF Core, HTTP clients, Quartz (Api only), runtime metrics.
### Testing
- Manual E2E tests use Playwright. Config is at `.playwright/cli.config.json`.
- To run E2E tests the frontend must be built into `src/Api/wwwroot/` and the Api must be running.
- Chrome/Chromium is the default for Playwright, if it fails try `--browser msedge`.

README.md +150 -0

diff --git a/README.md b/README.md
index 353813d..a057de2 100644
@@ -1,3 +1,153 @@
# Slopper
It produces slop!
Slopper picks a random piece of media from a Jellyfin database, uses AI to find a clippable moment, cuts it with FFmpeg, and stores the clip. Clips are viewable on the web frontend and can be uploaded to short-form platforms.
## Prerequisites
| Tool            | Version            | Notes                   |
| --------------- | ------------------ | ----------------------- |
| .NET SDK        | 11.0.100-preview.2 | Pinned in `global.json` |
| Node.js         | 26.1.0             |                         |
| corepack        | latest             | Manages pnpm            |
| pnpm            | (via corepack)     | Run `corepack install`  |
| FFmpeg          | any                | Required at runtime     |
| sqlite3         | any                | Required at runtime     |
| Chrome/Chromium | stable             | Required for E2E tests  |
**Recommended: use the devcontainer** — it installs everything automatically. VS Code with the Dev Containers extension will prompt you on open.
## Setup (first time)
These match the `postCreateCommand` in `.devcontainer/devcontainer.json`:
```sh
# Frontend deps
corepack install && pnpm ci
# .NET packages (locked)
dotnet restore --locked-mode
# .NET local tools (e.g. EF Core CLI)
dotnet tool restore
```
## Project Structure
```
src/
  Api/            # ASP.NET Core REST API
  Cli/            # .NET console app for local experimentation
  Domain/         # Core domain models and abstractions (class library)
  Frontend/       # Vue 3 + TypeScript SPA (Vite)
  Infrastructure/
    Ai/           # Ollama AI integration
    Database/     # EF Core / SQLite data access
    Ffmpeg/       # FFmpeg media processing
    YouTube/      # YouTube API integration
```
## Building Everything
```sh
# All .NET projects
dotnet build
# Frontend
pnpm -C src/Frontend build
```
## Development
### Frontend (`src/Frontend/`)
```sh
pnpm dev       # Vite dev server with hot reload
pnpm build     # Production build (vue-tsc + vite)
```
`pnpm dev` will output a "random" port once it starts.
### API (`src/Api/`)
```sh
dotnet run --project src/Api/Api.csproj
```
The Api project runs on port 5055 by default.
To perform end-to-end tests with both the `Frontend` and the `Api`, build the frontend and move the output from `src/Frontend/dist` to `src/Api/wwwroot`, then run the `Api` project. The `Api` project will serve the frontend from the same path.
For example, from project root:
```sh
pnpm -C src/Frontend build --emptyOutDir --outDir ../Api/wwwroot/
dotnet run --project src/Api/Api.csproj
```
### CLI (`src/Cli/`)
```sh
dotnet run --project src/Cli/Cli.csproj
```
The `Cli` is the primary experimentation tool — use it to test Domain and Infrastructure services in isolation. Edit `src/Cli/Program.cs` freely to test new features in new ways. Do not worry about checking in the experiments, it's fun to see the progression of the project.
The `Cli` is wired up like the `Api` but with some dependencies skipped so it's easier to run with.
### Domain (`src/Domain/`)
Pure class library — no runnable entry point. Built implicitly when building `Api` or `Cli`.
### Infrastructure / Integrations (`src/Infrastructure/`)
Pure class libraries consumed by `Api` and `Cli`.
## Configuration
Both `Api` and `Cli` use [.NET User Secrets](https://learn.microsoft.com/en-us/aspnet/core/security/app-secrets) for local configuration. The secrets shape is identical for both projects.
Create a `secrets.json` for the project you are running:
```sh
# API (ID: ad38b97a-09e9-4354-9c4f-710bf6b7a3ac)
dotnet user-secrets set "ConnectionStrings:slopper" "Data Source=<path>;" --project src/Api
# CLI (ID: 9df5410d-6a82-44ba-9e77-7ec4ffcf582a)
dotnet user-secrets set "ConnectionStrings:slopper" "Data Source=<path>;" --project src/Cli
```
Or edit the file directly. The full schema (all keys required):
```json
{
  "ConnectionStrings": {
    "jellyfin": "Data Source=<path-to-jellyfin.db>; Mode=ReadOnly;",
    "slopper": "Data Source=<path-to-slopper.db>;"
  },
  "ClipDirectory": "<absolute-path-to-media-directory>",
  "Ai": {
    "Endpoint": "<ollama-base-url>",
    "BasicAuth": "<base64-encoded user:password>",
    "DescriptionModel": "<model-name>",
    "EmbeddingModel": "<model-name>"
  },
  "YouTube": {
    "ClientId": "<google-oauth-client-id>",
    "ClientSecret": "<google-oauth-client-secret>",
    "User": "<youtube-channel-user>"
  }
}
```
The secrets file lives at:
- **Windows:** `%APPDATA%\Microsoft\UserSecrets\<ID>\secrets.json`
- **Linux/macOS:** `~/.microsoft/usersecrets/<ID>/secrets.json`
## Database Migrations
```sh
dotnet ef migrations add <MigrationName> --project src/Infrastructure/Database
```
Migrations are automatically run on startup of both the `Api` and the `Cli` projects.

package.json +12 -0

diff --git a/package.json b/package.json
new file mode 100644
index 0000000..0c0303a
@@ -0,0 +1,12 @@
{
  "name": "slopper",
  "private": true,
  "version": "0.0.0",
  "packageManager": "pnpm@11.1.2+sha512.415a1cc25974731e75455c1468371be74c5aa5fb7621b50d4056d222451609f11412f23fd602e6169f1e060466641f798597e1be961a10688836a67b16569499",
  "engines": {
    "node": "^26.1.0"
  },
  "devDependencies": {
    "@playwright/cli": "^0.1.13"
  }
}

pnpm-lock.yaml +1176 -0

Large diff (1176 lines changed) - not displayed

pnpm-workspace.yaml +2 -0

diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml
new file mode 100644
index 0000000..d37bf70
@@ -0,0 +1,2 @@
packages:
  - "src/Frontend"

src/Api/ClipGenerationJob.cs +17 -19

diff --git a/src/Api/ClipGenerationJob.cs b/src/Api/ClipGenerationJob.cs
index 4f2ddf3..572759e 100644
@@ -1,5 +1,4 @@
using System;
using System.ComponentModel.DataAnnotations;
using System.Threading.Tasks;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Logging;
@@ -31,14 +30,13 @@ public sealed class ClipGenerationJob(
            throw new JobExecutionException(ex, refireImmediately: true);
        }
        await context.Scheduler.ScheduleJob(
            TriggerBuilder
                .Create()
                .ForJob(Key)
                .StartAt(timeProvider.GetUtcNow() + options.CurrentValue.Interval)
                .Build(),
            context.CancellationToken
        );
        if (options.CurrentValue.Interval is TimeSpan interval)
        {
            await context.Scheduler.ScheduleJob(
                TriggerBuilder.Create().ForJob(Key).StartAt(timeProvider.GetUtcNow() + interval).Build(),
                context.CancellationToken
            );
        }
    }
}
@@ -46,10 +44,15 @@ public static class ClipGenerationJobExtensions
{
    extension(IServiceCollectionQuartzConfigurator quartz)
    {
        public IServiceCollectionQuartzConfigurator AddClipGenerationJob() =>
            quartz
                .AddJob<ClipGenerationJob>(ClipGenerationJob.Key, options => options.StoreDurably())
                .AddTrigger(options => options.ForJob(ClipGenerationJob.Key).StartNow());
        public IServiceCollectionQuartzConfigurator AddClipGenerationJob(bool startNow)
        {
            quartz.AddJob<ClipGenerationJob>(ClipGenerationJob.Key, options => options.StoreDurably());
            if (startNow)
            {
                quartz.AddTrigger(options => options.ForJob(ClipGenerationJob.Key).StartNow());
            }
            return quartz;
        }
    }
    extension(IServiceCollection services)
@@ -57,7 +60,6 @@ public static class ClipGenerationJobExtensions
        public IServiceCollection AddClipGenerationJobOptions()
        {
            services.AddOptions<ClipGenerationJobOptions>().BindConfiguration("ClipGenerationJob").ValidateOnStart();
            services.AddTransient<IValidateOptions<ClipGenerationJobOptions>, ClipGenerationJobOptionsValidator>();
            return services;
        }
@@ -66,9 +68,5 @@ public static class ClipGenerationJobExtensions
public sealed class ClipGenerationJobOptions
{
    [Required]
    public required TimeSpan Interval { get; set; }
    public TimeSpan? Interval { get; set; }
}
[OptionsValidator]
public sealed partial class ClipGenerationJobOptionsValidator : IValidateOptions<ClipGenerationJobOptions>;

src/Api/Program.cs +18 -12

diff --git a/src/Api/Program.cs b/src/Api/Program.cs
index 9c5b83c..6a9d0ca 100644
@@ -16,14 +16,18 @@ using Winton.Extensions.Configuration.Consul;
var builder = WebApplication.CreateBuilder(args);
builder.Configuration.AddConsul(
    "slopper",
    options =>
    {
        options.ConsulConfigurationOptions = options => options.Address = new(builder.Configuration["Consul:Address"]!);
        options.ReloadOnChange = true;
    }
);
if (!builder.Environment.IsDevelopment())
{
    builder.Configuration.AddConsul(
        "slopper",
        options =>
        {
            options.ConsulConfigurationOptions = options =>
                options.Address = new(builder.Configuration["Consul:Address"]!);
            options.ReloadOnChange = true;
        }
    );
}
builder.ConfigureOpenTelemetry();
@@ -35,20 +39,22 @@ builder.Services.AddJellyfinDatabase().AddSlopperDatabase().AddFfmpegServices().
builder
    .Services.AddClipGenerationJobOptions()
    .AddQuartz(quartz => quartz.AddClipGenerationJob().AddCleanupJob().AddUploadJob())
    .AddQuartz(quartz =>
        quartz.AddClipGenerationJob(startNow: !builder.Environment.IsDevelopment()).AddCleanupJob().AddUploadJob()
    )
    .AddQuartzServer();
builder.Services.AddAuthentication(CookieAuthenticationDefaults.AuthenticationScheme).AddCookie().AddYouTube();
builder.Services.AddAuthorizationBuilder().AddYouTubePolicy();
using var app = builder.Build();
if (builder.Environment.IsDevelopment())
{
    app.UseCookiePolicy(new() { MinimumSameSitePolicy = SameSiteMode.Lax });
    builder.Services.Configure<CookiePolicyOptions>(options => options.MinimumSameSitePolicy = SameSiteMode.Lax);
}
using var app = builder.Build();
app.UseAuthentication();
app.UseAuthorization();

src/Api/appsettings.Development.json +1 -1

diff --git a/src/Api/appsettings.Development.json b/src/Api/appsettings.Development.json
index 271e1d3..69ec8dc 100644
@@ -7,7 +7,7 @@
    }
  },
  "ClipGenerationJob": {
    "Interval": "00:00:10.000"
    "Interval": null
  },
  "Cleaner": {
    "Retention": "00:05:00"

src/Frontend/openapi.json +0 -221

diff --git a/src/Frontend/openapi.json b/src/Frontend/openapi.json
deleted file mode 100644
index 4e5d5f9..0000000
@@ -1,221 +0,0 @@
{
  "openapi": "3.1.2",
  "info": {
    "title": "Slopper.Api | v1",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "http://localhost:5055"
    }
  ],
  "paths": {
    "/api/clips": {
      "get": {
        "tags": [
          "ApiEndpoints"
        ],
        "parameters": [
          {
            "name": "after",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "maximum": 64,
              "minimum": 0,
              "pattern": "^-?(?:0|[1-9]\\d*)$",
              "type": [
                "integer",
                "string"
              ],
              "format": "int32",
              "default": 10
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Clip"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/clips/{id}/stream": {
      "get": {
        "tags": [
          "ApiEndpoints"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "404": {
            "description": "Not Found"
          }
        }
      }
    },
    "/api/jobs": {
      "get": {
        "tags": [
          "ApiEndpoints"
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JobStatus"
                }
              }
            }
          }
        }
      },
      "put": {
        "tags": [
          "ApiEndpoints"
        ],
        "summary": "Triggers a job generating a new clip.",
        "responses": {
          "202": {
            "description": "Accepted"
          }
        }
      }
    },
    "/api/youtube/login": {
      "get": {
        "tags": [
          "YouTubeApiEndpoints"
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/api/youtube/upload": {
      "get": {
        "tags": [
          "YouTubeApiEndpoints"
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JobStatus"
                }
              }
            }
          }
        }
      },
      "put": {
        "tags": [
          "YouTubeApiEndpoints"
        ],
        "responses": {
          "202": {
            "description": "Accepted"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Clip": {
        "required": [
          "id",
          "duration",
          "createdAt",
          "caption",
          "tags"
        ],
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "duration": {
            "pattern": "^-?(\\d+\\.)?\\d{2}:\\d{2}:\\d{2}(\\.\\d{1,7})?$",
            "type": "string"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "caption": {
            "type": [
              "null",
              "string"
            ]
          },
          "tags": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      },
      "JobStatus": {
        "required": [
          "isRunning"
        ],
        "type": "object",
        "properties": {
          "isRunning": {
            "type": "boolean"
          },
          "nextScheduledRun": {
            "type": [
              "null",
              "string"
            ],
            "format": "date-time"
          }
        }
      }
    }
  },
  "tags": [
    {
      "name": "ApiEndpoints"
    },
    {
      "name": "YouTubeApiEndpoints"
    }
  ]
}

src/Frontend/package-lock.json +0 -1736

Large diff (1736 lines changed) - not displayed

src/Frontend/package.json +4 -0

diff --git a/src/Frontend/package.json b/src/Frontend/package.json
index 3e40ffb..99bb469 100644
@@ -3,6 +3,10 @@
  "private": true,
  "version": "0.0.0",
  "type": "module",
  "packageManager": "pnpm@11.1.2+sha512.415a1cc25974731e75455c1468371be74c5aa5fb7621b50d4056d222451609f11412f23fd602e6169f1e060466641f798597e1be961a10688836a67b16569499",
  "engines": {
    "node": "^26.1.0"
  },
  "scripts": {
    "dev": "vite",
    "build": "vue-tsc -b && vite build",

src/Frontend/vite.config.ts +0 -6

diff --git a/src/Frontend/vite.config.ts b/src/Frontend/vite.config.ts
index 6148a60..e3d9890 100644
@@ -4,10 +4,4 @@ import vue from "@vitejs/plugin-vue";
// https://vite.dev/config/
export default defineConfig({
  plugins: [vue()],
  server: {
    port: 5055,
    proxy: {
      "/api": "http://localhost:5056",
    },
  },
});