@askjo/camofox-browser 1.5.1 → 1.6.0

package/plugins/youtube/index.js

@@ -0,0 +1,206 @@
+/**
+ * YouTube transcript plugin.
+ *
+ * Extracts video transcripts via yt-dlp (preferred) with browser fallback.
+ * Registers POST /youtube/transcript.
+ */
+
+import { detectYtDlp, hasYtDlp, ensureYtDlp, ytDlpTranscript, parseJson3, parseVtt, parseXml } from './youtube.js';
+import { classifyError } from '../../lib/request-utils.js';
+
+export async function register(app, ctx, pluginConfig = {}) {
+  const { log, config, sessions, ensureBrowser, getSession,
+          withUserLimit, safePageClose, normalizeUserId,
+          validateUrl, safeError, buildProxyUrl, proxyPool,
+          failuresTotal } = ctx;
+
+  const NAVIGATE_TIMEOUT_MS = config.navigateTimeoutMs;
+
+  // Detect yt-dlp binary at load time
+  await detectYtDlp(log);
+
+  // Auth is on by default; set { "auth": false } in camofox.config.json to disable
+  // Auth off by default — matches pre-plugin behavior. Set { "auth": true } to require auth.
+  const middleware = pluginConfig.auth === true ? ctx.auth() : (_req, _res, next) => next();
+
+  app.post('/youtube/transcript', middleware, async (req, res) => {
+    const reqId = req.reqId;
+    try {
+      const { url, languages = ['en'] } = req.body;
+      if (!url) return res.status(400).json({ error: 'url is required' });
+
+      const urlErr = validateUrl(url);
+      if (urlErr) return res.status(400).json({ error: urlErr });
+
+      const videoIdMatch = url.match(
+        /(?:youtube\.com\/watch\?v=|youtu\.be\/|youtube\.com\/embed\/|youtube\.com\/shorts\/)([a-zA-Z0-9_-]{11})/
+      );
+      if (!videoIdMatch) {
+        return res.status(400).json({ error: 'Could not extract YouTube video ID from URL' });
+      }
+      const videoId = videoIdMatch[1];
+      const lang = languages[0] || 'en';
+
+      // Re-detect yt-dlp if startup detection failed (transient issue)
+      await ensureYtDlp(log);
+
+      const ytDlpProxyUrl = buildProxyUrl(proxyPool, config.proxy);
+      log('info', 'youtube transcript: starting', { reqId, videoId, lang, method: hasYtDlp() ? 'yt-dlp' : 'browser', hasProxy: !!ytDlpProxyUrl });
+
+      let result;
+      if (hasYtDlp()) {
+        try {
+          result = await ytDlpTranscript(reqId, url, videoId, lang, ytDlpProxyUrl);
+        } catch (ytErr) {
+          log('warn', 'yt-dlp threw, falling back to browser', { reqId, error: ytErr.message });
+          result = null;
+        }
+        // If yt-dlp returned an error result (e.g. no captions) or threw, try browser
+        if (!result || result.status !== 'ok') {
+          if (result) log('warn', 'yt-dlp returned error, falling back to browser', { reqId, status: result.status, code: result.code });
+          result = await browserTranscript(reqId, url, videoId, lang);
+        }
+      } else {
+        result = await browserTranscript(reqId, url, videoId, lang);
+      }
+
+      log('info', 'youtube transcript: done', { reqId, videoId, status: result.status, words: result.total_words });
+      res.json(result);
+    } catch (err) {
+      failuresTotal.labels(classifyError(err), 'youtube_transcript').inc();
+      log('error', 'youtube transcript failed', { reqId, error: err.message, stack: err.stack });
+      res.status(500).json({ error: safeError(err) });
+    }
+  });
+
+  // Browser fallback — play video, intercept timedtext network response
+  async function browserTranscript(reqId, url, videoId, lang) {
+    return await withUserLimit('__yt_transcript__', async () => {
+      await ensureBrowser();
+      const session = await getSession('__yt_transcript__');
+      const page = await session.context.newPage();
+
+      try {
+        await page.addInitScript(() => {
+          const origPlay = HTMLMediaElement.prototype.play;
+          HTMLMediaElement.prototype.play = function() { this.volume = 0; this.muted = true; return origPlay.call(this); };
+        });
+
+        let interceptedCaptions = null;
+        page.on('response', async (response) => {
+          const respUrl = response.url();
+          if (respUrl.includes('/api/timedtext') && respUrl.includes(`v=${videoId}`) && !interceptedCaptions) {
+            try {
+              const body = await response.text();
+              if (body && body.length > 0) interceptedCaptions = body;
+            } catch {}
+          }
+        });
+
+        await page.goto(url, { waitUntil: 'domcontentloaded', timeout: NAVIGATE_TIMEOUT_MS });
+        await page.waitForTimeout(2000);
+
+        // Extract caption track URLs and metadata from ytInitialPlayerResponse
+        const meta = await page.evaluate(() => {
+          const r = window.ytInitialPlayerResponse || (typeof ytInitialPlayerResponse !== 'undefined' ? ytInitialPlayerResponse : null);
+          if (!r) return { title: '', tracks: [] };
+          const tracks = r?.captions?.playerCaptionsTracklistRenderer?.captionTracks || [];
+          return {
+            title: r?.videoDetails?.title || '',
+            tracks: tracks.map(t => ({ code: t.languageCode, name: t.name?.simpleText || t.languageCode, kind: t.kind || 'manual', url: t.baseUrl })),
+          };
+        });
+
+        log('info', 'youtube transcript: extracted caption tracks', { reqId, title: meta.title, trackCount: meta.tracks.length, tracks: meta.tracks.map(t => t.code) });
+
+        // Strategy A: Fetch caption track URL directly from ytInitialPlayerResponse
+        if (meta.tracks && meta.tracks.length > 0) {
+          const track = meta.tracks.find(t => t.code === lang) || meta.tracks[0];
+          if (track && track.url) {
+            const captionUrl = track.url + (track.url.includes('?') ? '&' : '?') + 'fmt=json3';
+            log('info', 'youtube transcript: fetching caption track', { reqId, lang: track.code, url: captionUrl.substring(0, 100) });
+            try {
+              const captionResp = await page.evaluate(async (fetchUrl) => {
+                const resp = await fetch(fetchUrl);
+                return resp.ok ? await resp.text() : null;
+              }, captionUrl);
+              if (captionResp && captionResp.length > 0) {
+                let transcriptText = null;
+                if (captionResp.trimStart().startsWith('{')) transcriptText = parseJson3(captionResp);
+                else if (captionResp.includes('WEBVTT')) transcriptText = parseVtt(captionResp);
+                else if (captionResp.includes('<text')) transcriptText = parseXml(captionResp);
+                if (transcriptText && transcriptText.trim()) {
+                  return {
+                    status: 'ok', transcript: transcriptText,
+                    video_url: url, video_id: videoId, video_title: meta.title,
+                    language: track.code, total_words: transcriptText.split(/\s+/).length,
+                    available_languages: meta.tracks.map(t => ({ code: t.code, name: t.name, kind: t.kind })),
+                  };
+                }
+              }
+            } catch (fetchErr) {
+              log('warn', 'youtube transcript: caption track fetch failed', { reqId, error: fetchErr.message });
+            }
+          }
+        }
+
+        // Strategy B: Play video and intercept timedtext network response
+        await page.evaluate(() => {
+          const v = document.querySelector('video');
+          if (v) { v.muted = true; v.play().catch(() => {}); }
+        }).catch(() => {});
+
+        for (let i = 0; i < 40 && !interceptedCaptions; i++) {
+          await page.waitForTimeout(500);
+        }
+
+        if (!interceptedCaptions) {
+          return {
+            status: 'error', code: 404,
+            message: 'No captions available for this video',
+            video_url: url, video_id: videoId, title: meta.title,
+          };
+        }
+
+        log('info', 'youtube transcript: intercepted captions', { reqId, len: interceptedCaptions.length });
+
+        let transcriptText = null;
+        if (interceptedCaptions.trimStart().startsWith('{')) transcriptText = parseJson3(interceptedCaptions);
+        else if (interceptedCaptions.includes('WEBVTT')) transcriptText = parseVtt(interceptedCaptions);
+        else if (interceptedCaptions.includes('<text')) transcriptText = parseXml(interceptedCaptions);
+
+        if (!transcriptText || !transcriptText.trim()) {
+          return {
+            status: 'error', code: 404,
+            message: 'Caption data intercepted but could not be parsed',
+            video_url: url, video_id: videoId, title: meta.title,
+          };
+        }
+
+        return {
+          status: 'ok', transcript: transcriptText,
+          video_url: url, video_id: videoId, video_title: meta.title,
+          language: lang, total_words: transcriptText.split(/\s+/).length,
+          available_languages: meta.languages,
+        };
+      } finally {
+        await safePageClose(page);
+        // Clean up transcript session if no live pages remain
+        const ytKey = normalizeUserId('__yt_transcript__');
+        const ytSession = sessions.get(ytKey);
+        if (ytSession && !ytSession._closing) {
+          try {
+            const remainingPages = ytSession.context.pages();
+            if (remainingPages.length === 0) {
+              ytSession._closing = true;
+              ytSession.context.close().catch(() => {});
+              sessions.delete(ytKey);
+            }
+          } catch {
+            sessions.delete(ytKey);
+          }
+        }
+      }
+    });
+  }
+}

package/plugins/youtube/post-install.sh

@@ -0,0 +1,5 @@
+#!/bin/sh
+# Install yt-dlp binary (not available via apt)
+set -e
+curl -fL https://github.com/yt-dlp/yt-dlp/releases/latest/download/yt-dlp -o /usr/local/bin/yt-dlp
+chmod +x /usr/local/bin/yt-dlp

package/plugins/youtube/youtube.test.js

@@ -0,0 +1,41 @@
+import { parseJson3, parseVtt, parseXml } from './youtube.js';
+
+describe('YouTube transcript parsers', () => {
+  test('parseJson3 extracts timestamped text', () => {
+    const json3 = JSON.stringify({
+      events: [
+        { tStartMs: 0, segs: [{ utf8: 'Hello' }] },
+        { tStartMs: 65000, segs: [{ utf8: 'World' }] },
+      ],
+    });
+    const result = parseJson3(json3);
+    expect(result).toBe('[00:00] Hello\n[01:05] World');
+  });
+
+  test('parseVtt extracts text from VTT', () => {
+    const vtt = `WEBVTT
+
+00:00:01.000 --> 00:00:04.000
+Hello there
+
+00:01:05.000 --> 00:01:09.000
+General Kenobi`;
+    const result = parseVtt(vtt);
+    expect(result).toContain('[00:01] Hello there');
+    expect(result).toContain('[01:05] General Kenobi');
+  });
+
+  test('parseXml extracts text from XML captions', () => {
+    const xml = '<text start="0" dur="3">First line</text><text start="65.5" dur="2">Second line</text>';
+    const result = parseXml(xml);
+    expect(result).toBe('[00:00] First line\n[01:05] Second line');
+  });
+
+  test('parseJson3 handles empty events', () => {
+    expect(parseJson3(JSON.stringify({ events: [] }))).toBe('');
+  });
+
+  test('parseJson3 handles malformed JSON', () => {
+    expect(parseJson3('not json')).toBeNull();
+  });
+});

package/scripts/install-plugin-deps.sh

@@ -0,0 +1,63 @@
+#!/bin/sh
+# Install system packages declared by plugins listed in camofox.config.json.
+# Each plugin can have an apt.txt (one package per line) and a post-install.sh.
+# If no config file or no plugins key, installs deps for all plugins in plugins/.
+
+set -e
+
+CONFIG="/app/camofox.config.json"
+PLUGINS_DIR="/app/plugins"
+
+# Read plugin list from camofox.config.json, or fall back to all plugin dirs
+if [ -f "$CONFIG" ] && command -v node >/dev/null 2>&1; then
+  PLUGIN_LIST=$(node -e "
+    const c = JSON.parse(require('fs').readFileSync('$CONFIG','utf-8'));
+    if (Array.isArray(c.plugins)) {
+      console.log(c.plugins.join(' '));
+    } else if (c.plugins && typeof c.plugins === 'object') {
+      console.log(Object.entries(c.plugins)
+        .filter(([, v]) => v && v.enabled !== false)
+        .map(([k]) => k)
+        .join(' '));
+    }
+  " 2>/dev/null || echo "")
+fi
+
+if [ -z "$PLUGIN_LIST" ]; then
+  # No config or no plugins key — use all plugin directories
+  PLUGIN_LIST=""
+  for d in "$PLUGINS_DIR"/*/; do
+    [ -d "$d" ] || continue
+    name=$(basename "$d")
+    case "$name" in _*|.*) continue ;; esac
+    PLUGIN_LIST="$PLUGIN_LIST $name"
+  done
+fi
+
+echo "[install-plugin-deps] Plugins:$PLUGIN_LIST"
+
+# Collect apt packages
+PKGS=""
+for name in $PLUGIN_LIST; do
+  f="$PLUGINS_DIR/$name/apt.txt"
+  [ -f "$f" ] || continue
+  while IFS= read -r line; do
+    case "$line" in \#*|"") continue ;; esac
+    PKGS="$PKGS $line"
+  done < "$f"
+done
+
+if [ -n "$PKGS" ]; then
+  echo "[install-plugin-deps] Installing:$PKGS"
+  apt-get update && apt-get install -y $PKGS && rm -rf /var/lib/apt/lists/*
+else
+  echo "[install-plugin-deps] No apt dependencies"
+fi
+
+# Run post-install hooks
+for name in $PLUGIN_LIST; do
+  hook="$PLUGINS_DIR/$name/post-install.sh"
+  [ -x "$hook" ] || continue
+  echo "[install-plugin-deps] Running post-install for $name"
+  "$hook"
+done

package/scripts/plugin.js

@@ -0,0 +1,342 @@
+#!/usr/bin/env node
+
+/**
+ * camofox plugin manager — install, remove, and list plugins.
+ *
+ * Usage:
+ *   node scripts/plugin.js install <source>   Install a plugin from git URL or local path
+ *   node scripts/plugin.js remove <name>      Remove a plugin and its config entry
+ *   node scripts/plugin.js list               List installed plugins and their source
+ *
+ * Sources:
+ *   git:github.com/user/repo                  Git shorthand
+ *   https://github.com/user/repo              Git URL
+ *   /absolute/path/to/plugin-dir              Local directory (copied)
+ *   ./relative/path/to/plugin-dir             Local directory (copied)
+ *
+ * Plugin name is inferred from the repo/directory name. If the repo root has
+ * an index.js with register(), it's used directly. If it has a plugins/ subdir,
+ * each subdirectory is installed as a separate plugin.
+ *
+ * After install, the plugin is added to camofox.config.json plugins[] and
+ * npm dependencies are installed if the plugin has a package.json.
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { execSync } from 'child_process';
+import { fileURLToPath } from 'url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const ROOT = path.join(__dirname, '..');
+const PLUGINS_DIR = path.join(ROOT, 'plugins');
+const CONFIG_PATH = path.join(ROOT, 'camofox.config.json');
+
+// ── Config helpers ──────────────────────────────────────────────────────────
+
+function readConfig() {
+  try {
+    return JSON.parse(fs.readFileSync(CONFIG_PATH, 'utf-8'));
+  } catch {
+    return { id: 'camofox-browser', name: 'Camofox Browser', version: '0.0.0', plugins: [] };
+  }
+}
+
+function writeConfig(config) {
+  fs.writeFileSync(CONFIG_PATH, JSON.stringify(config, null, 2) + '\n');
+}
+
+/**
+ * Get the set of enabled plugin names from config.
+ * Handles both array format ["youtube"] and object format { "youtube": { "enabled": true } }.
+ */
+function getEnabledPlugins(config) {
+  if (!config.plugins) return new Set();
+  if (Array.isArray(config.plugins)) return new Set(config.plugins);
+  if (typeof config.plugins === 'object') {
+    const enabled = new Set();
+    for (const [name, conf] of Object.entries(config.plugins)) {
+      if (conf === false || (typeof conf === 'object' && conf.enabled === false)) continue;
+      enabled.add(name);
+    }
+    return enabled;
+  }
+  return new Set();
+}
+
+function addToConfig(name) {
+  const config = readConfig();
+  if (Array.isArray(config.plugins)) {
+    if (!config.plugins.includes(name)) {
+      config.plugins.push(name);
+      writeConfig(config);
+    }
+  } else if (typeof config.plugins === 'object') {
+    if (!config.plugins[name] || config.plugins[name].enabled === false) {
+      config.plugins[name] = config.plugins[name] || {};
+      config.plugins[name].enabled = true;
+      writeConfig(config);
+    }
+  } else {
+    config.plugins = [name];
+    writeConfig(config);
+  }
+}
+
+function removeFromConfig(name) {
+  const config = readConfig();
+  if (Array.isArray(config.plugins)) {
+    config.plugins = config.plugins.filter(p => p !== name);
+    writeConfig(config);
+  } else if (typeof config.plugins === 'object' && config.plugins[name] !== undefined) {
+    delete config.plugins[name];
+    writeConfig(config);
+  }
+}
+
+// ── Source parsing ──────────────────────────────────────────────────────────
+
+function parseSource(source) {
+  // Local path
+  if (source.startsWith('/') || source.startsWith('./') || source.startsWith('../')) {
+    const resolved = path.resolve(source);
+    if (!fs.existsSync(resolved)) {
+      fatal(`Local path not found: ${resolved}`);
+    }
+    if (!fs.statSync(resolved).isDirectory()) {
+      fatal(`Source must be a directory: ${resolved}`);
+    }
+    return { type: 'local', path: resolved, name: path.basename(resolved) };
+  }
+
+  // Git URL — https://, ssh://, git@, git:
+  let gitUrl = source;
+  if (gitUrl.startsWith('git:')) {
+    gitUrl = gitUrl.slice(4);
+    // git:github.com/user/repo → https://github.com/user/repo
+    if (!gitUrl.startsWith('http') && !gitUrl.startsWith('ssh://') && !gitUrl.startsWith('git@')) {
+      gitUrl = `https://${gitUrl}`;
+    }
+  }
+
+  // Strip trailing .git
+  gitUrl = gitUrl.replace(/\.git$/, '');
+
+  // Extract name from URL
+  const name = gitUrl.split('/').pop().replace(/[^a-zA-Z0-9_-]/g, '');
+  if (!name) fatal(`Cannot infer plugin name from: ${source}`);
+
+  // Re-add .git for clone
+  const cloneUrl = gitUrl.endsWith('.git') ? gitUrl : `${gitUrl}.git`;
+
+  return { type: 'git', url: cloneUrl, name };
+}
+
+// ── Install ─────────────────────────────────────────────────────────────────
+
+function isPluginDir(dir) {
+  const indexPath = path.join(dir, 'index.js');
+  if (!fs.existsSync(indexPath)) return false;
+  const content = fs.readFileSync(indexPath, 'utf-8');
+  return /\bregister\b/.test(content);
+}
+
+function installFromLocal(srcDir, name) {
+  const destDir = path.join(PLUGINS_DIR, name);
+  if (fs.existsSync(destDir)) {
+    fatal(`Plugin "${name}" already exists. Remove it first: node scripts/plugin.js remove ${name}`);
+  }
+  copyDirSync(srcDir, destDir);
+  return [name];
+}
+
+function installFromGit(url, name) {
+  const tmpDir = path.join(ROOT, '.tmp-plugin-clone');
+  try {
+    if (fs.existsSync(tmpDir)) fs.rmSync(tmpDir, { recursive: true });
+
+    console.log(`Cloning ${url}...`);
+    execSync(`git clone --depth 1 ${url} ${tmpDir}`, { stdio: 'pipe' });
+
+    // Case 1: Root is a plugin (has index.js with register)
+    if (isPluginDir(tmpDir)) {
+      return installFromLocal(tmpDir, name);
+    }
+
+    // Case 2: Has plugins/ subdir with plugin directories
+    const pluginsSubdir = path.join(tmpDir, 'plugins');
+    if (fs.existsSync(pluginsSubdir) && fs.statSync(pluginsSubdir).isDirectory()) {
+      const installed = [];
+      for (const entry of fs.readdirSync(pluginsSubdir, { withFileTypes: true })) {
+        if (!entry.isDirectory()) continue;
+        if (entry.name.startsWith('_') || entry.name.startsWith('.')) continue;
+        const subDir = path.join(pluginsSubdir, entry.name);
+        if (isPluginDir(subDir)) {
+          installFromLocal(subDir, entry.name);
+          installed.push(entry.name);
+        }
+      }
+      if (installed.length === 0) {
+        fatal(`No plugins found in ${url} — expected index.js with register() at root or in plugins/*/`);
+      }
+      return installed;
+    }
+
+    fatal(`No plugins found in ${url} — expected index.js with register() at root or plugins/*/ subdirs`);
+  } finally {
+    if (fs.existsSync(tmpDir)) fs.rmSync(tmpDir, { recursive: true });
+  }
+}
+
+function installPluginDeps(name) {
+  const pluginDir = path.join(PLUGINS_DIR, name);
+
+  // npm install if package.json exists
+  const pkgJson = path.join(pluginDir, 'package.json');
+  if (fs.existsSync(pkgJson)) {
+    console.log(`Installing npm dependencies for ${name}...`);
+    execSync('npm install --omit=dev', { cwd: pluginDir, stdio: 'inherit' });
+  }
+
+  // Check for apt.txt / post-install.sh (just warn — can't run apt locally)
+  if (fs.existsSync(path.join(pluginDir, 'apt.txt'))) {
+    console.log(`⚠  ${name} has apt.txt — system packages need Docker build or manual install`);
+  }
+  if (fs.existsSync(path.join(pluginDir, 'post-install.sh'))) {
+    console.log(`⚠  ${name} has post-install.sh — run it manually or rebuild Docker image`);
+  }
+}
+
+// ── Remove ──────────────────────────────────────────────────────────────────
+
+function removePlugin(name) {
+  const pluginDir = path.join(PLUGINS_DIR, name);
+  if (!fs.existsSync(pluginDir)) {
+    fatal(`Plugin "${name}" not found in plugins/`);
+  }
+
+  fs.rmSync(pluginDir, { recursive: true });
+  removeFromConfig(name);
+  console.log(`✓ Removed plugin "${name}"`);
+}
+
+// ── List ────────────────────────────────────────────────────────────────────
+
+function listPlugins() {
+  const config = readConfig();
+  const configPlugins = getEnabledPlugins(config);
+
+  if (!fs.existsSync(PLUGINS_DIR)) {
+    console.log('No plugins directory.');
+    return;
+  }
+
+  const entries = fs.readdirSync(PLUGINS_DIR, { withFileTypes: true });
+  const plugins = entries
+    .filter(e => e.isDirectory() && !e.name.startsWith('_') && !e.name.startsWith('.'))
+    .map(e => e.name);
+
+  if (plugins.length === 0) {
+    console.log('No plugins installed.');
+    return;
+  }
+
+  console.log('Installed plugins:\n');
+  for (const name of plugins.sort()) {
+    const enabled = configPlugins.size === 0 || configPlugins.has(name);
+    const status = enabled ? '✓' : '○';
+    const hasTest = fs.existsSync(path.join(PLUGINS_DIR, name, `${name}.test.js`))
+      || fs.readdirSync(path.join(PLUGINS_DIR, name)).some(f => f.endsWith('.test.js'));
+    const hasDeps = fs.existsSync(path.join(PLUGINS_DIR, name, 'apt.txt'))
+      || fs.existsSync(path.join(PLUGINS_DIR, name, 'post-install.sh'));
+    const hasPkg = fs.existsSync(path.join(PLUGINS_DIR, name, 'package.json'));
+
+    const flags = [
+      hasTest ? 'tests' : null,
+      hasDeps ? 'sys-deps' : null,
+      hasPkg ? 'npm-deps' : null,
+    ].filter(Boolean).join(', ');
+
+    console.log(`  ${status} ${name}${flags ? `  (${flags})` : ''}`);
+  }
+
+  if (configPlugins.size > 0) {
+    console.log(`\n${configPlugins.size} plugin(s) enabled in camofox.config.json`);
+  } else {
+    console.log('\nNo plugins[] in config — all plugins are loaded');
+  }
+}
+
+// ── Helpers ─────────────────────────────────────────────────────────────────
+
+function copyDirSync(src, dest) {
+  fs.mkdirSync(dest, { recursive: true });
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+    // Skip .git, node_modules
+    if (entry.name === '.git' || entry.name === 'node_modules') continue;
+    if (entry.isDirectory()) {
+      copyDirSync(srcPath, destPath);
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+function fatal(msg) {
+  console.error(`Error: ${msg}`);
+  process.exit(1);
+}
+
+// ── CLI ─────────────────────────────────────────────────────────────────────
+
+const [,, action, ...args] = process.argv;
+
+switch (action) {
+  case 'install': {
+    const source = args[0];
+    if (!source) fatal('Usage: plugin install <git-url|local-path>');
+
+    const parsed = parseSource(source);
+    const installed = parsed.type === 'git'
+      ? installFromGit(parsed.url, parsed.name)
+      : installFromLocal(parsed.path, parsed.name);
+
+    for (const name of installed) {
+      addToConfig(name);
+      installPluginDeps(name);
+    }
+
+    console.log(`\n✓ Installed: ${installed.join(', ')}`);
+    console.log('  Restart the server to load new plugin(s).');
+    break;
+  }
+
+  case 'remove': {
+    const name = args[0];
+    if (!name) fatal('Usage: plugin remove <name>');
+    removePlugin(name);
+    break;
+  }
+
+  case 'list':
+  case 'ls': {
+    listPlugins();
+    break;
+  }
+
+  default:
+    console.log(`camofox plugin manager
+
+Usage:
+  node scripts/plugin.js install <source>   Install from git URL or local path
+  node scripts/plugin.js remove <name>      Remove a plugin
+  node scripts/plugin.js list               List installed plugins
+
+Sources:
+  git:github.com/user/repo
+  https://github.com/user/repo
+  ./path/to/local/plugin`);
+    if (action) process.exit(1);
+}