atris 3.53.0 → 3.55.0

package/commands/youtube.js

@@ -1,7 +1,8 @@
 const { apiRequestJson } = require('../utils/api');
-const { ensureValidCredentials } = require('../utils/auth');
+const { ensureBilledCommandAuth } = require('./auth');
 const { spawnSync } = require('child_process');
 const fs = require('fs');
+const os = require('os');
 const path = require('path');
 const https = require('https');
 
@@ -25,7 +26,9 @@ const ALLOWED_CAPTION_HOST_SUFFIXES = [
 
 function showYoutubeHelp(output = console.log, commandName = 'atris youtube') {
   output('');
-  output(`Usage: ${commandName} notes <youtube-url> [youtube-url-or-playlist...] [engine]`);
+  output(`Usage: ${commandName} search "<query>" [--limit N] [--json]`);
+  output(`       ${commandName} search --paid "<query>" [--limit N] [--json]`);
+  output(`       ${commandName} notes <youtube-url> [youtube-url-or-playlist...] [engine]`);
   output(`       ${commandName} process <youtube-url> [options]`);
   output(`       ${commandName} digest [--days N]`);
   output(`       ${commandName} watch add <channel-url-or-@handle>`);
@@ -34,6 +37,8 @@ function showYoutubeHelp(output = console.log, commandName = 'atris youtube') {
   output(`       ${commandName} watch tick`);
   output(`       ${commandName} <youtube-url> [options]`);
   output('');
+  output('search = free local discovery (ytsearch / yt-dlp), returns youtu.be links');
+  output('search --paid = 5 credits, watch permalinks + titles from Atris');
   output('notes = free local notes for one url, several urls, or a playlist');
   output('process = 5 credits cloud knowledge');
   output('digest = one decision page from this week\'s video briefs');
@@ -42,6 +47,8 @@ function showYoutubeHelp(output = console.log, commandName = 'atris youtube') {
   output('Falls back to cloud video processing when local captions are unavailable.');
   output('');
   output('Options:');
+  output('  --limit <n>         Max search results (default: 5)');
+  output('  --paid              Bill 5 credits for watch permalinks (search only)');
   output('  --query, -q <text>  Focus question for the analysis');
   output('  --agent <id>        Agent id to store knowledge against');
   output('  --store             Save as agent knowledge (requires --agent)');
@@ -53,6 +60,9 @@ function showYoutubeHelp(output = console.log, commandName = 'atris youtube') {
   output('  metadata -> timestamped outline -> claims -> examples -> takeaways -> Atris implications -> next actions');
   output('');
   output('Examples:');
+  output(`  ${commandName} search "MCP agents 2026"`);
+  output(`  ${commandName} search "MCP agents" --limit 10`);
+  output(`  ${commandName} search --paid "MCP agents 2026"`);
   output(`  ${commandName} notes https://www.youtube.com/watch?v=VIDEO_ID`);
   output(`  ${commandName} notes https://www.youtube.com/watch?v=VIDEO_ID https://youtu.be/OTHER_ID`);
   output(`  ${commandName} notes https://www.youtube.com/playlist?list=PLAYLIST_ID`);
@@ -384,14 +394,36 @@ async function extractLocalTranscript(youtubeUrl, deps = {}) {
 
 async function processYoutube(options, deps = {}) {
   const apiFn = deps.apiRequestJson || apiRequestJson;
-  const ensureFn = deps.ensureValidCredentials || ensureValidCredentials;
-  const ensured = await ensureFn(apiFn);
-  const creds = ensured && ensured.credentials;
-  if (!creds?.token) {
-    const detail = ensured?.detail || ensured?.error;
-    throw new Error(detail ? `Authentication failed: ${detail}. Run "atris login".` : 'Not logged in. Run "atris login".');
+  const ensureBilled = deps.ensureBilledCommandAuth || ensureBilledCommandAuth;
+  let auth = await ensureBilled('youtube', deps);
+  if (!auth?.ok || !auth.token) {
+    throw new Error(auth?.error || 'not signed in. run atris login first.');
   }
 
+  const requestYoutube = async (body) => {
+    let result = await apiFn('/agent/process_youtube', {
+      method: 'POST',
+      token: auth.token,
+      timeoutMs: options.timeoutMs,
+      retries: 0,
+      body,
+    });
+    if (!result.ok && result.status === 401 && !auth.minted) {
+      const remint = await ensureBilled('youtube', { ...deps, forceMint: true });
+      if (remint?.ok && remint.token) {
+        auth = remint;
+        result = await apiFn('/agent/process_youtube', {
+          method: 'POST',
+          token: auth.token,
+          timeoutMs: options.timeoutMs,
+          retries: 0,
+          body,
+        });
+      }
+    }
+    return result;
+  };
+
   const localExtractor = deps.extractLocalTranscript || extractLocalTranscript;
   let localTranscript = null;
   try {
@@ -401,13 +433,9 @@ async function processYoutube(options, deps = {}) {
   }
 
   if (localTranscript?.transcriptText) {
-    const transcriptResult = await apiFn('/agent/process_youtube', {
-      method: 'POST',
-      token: creds.token,
-      timeoutMs: options.timeoutMs,
-      retries: 0,
-      body: buildYoutubePayload({ ...options, localTranscript, cacheTranscript: false }),
-    });
+    const transcriptResult = await requestYoutube(
+      buildYoutubePayload({ ...options, localTranscript, cacheTranscript: false }),
+    );
 
     if (transcriptResult.ok) {
       return transcriptResult.data;
@@ -418,13 +446,7 @@ async function processYoutube(options, deps = {}) {
     }
   }
 
-  const result = await apiFn('/agent/process_youtube', {
-    method: 'POST',
-    token: creds.token,
-    timeoutMs: options.timeoutMs,
-    retries: 0,
-    body: buildYoutubePayload(options),
-  });
+  const result = await requestYoutube(buildYoutubePayload(options));
 
   if (!result.ok) {
     throw youtubeFailureError(result);
@@ -1226,8 +1248,500 @@ function runYoutubeNotes(args = [], deps = {}) {
   return runYoutubeNotesBatch(parsed, deps);
 }
 
+const DEFAULT_SEARCH_LIMIT = 5;
+const PAID_SEARCH_TIMEOUT_MS = 120000;
+const PAID_SEARCH_COST_HINT = '5 credits per search';
+const YTSEARCH_USAGE = 'usage: atris youtube search "<query>" [--limit N] [--json]';
+const SEARCH_PRINT_FORMAT = '%(title)s | %(channel)s | %(duration_string)s | %(view_count)s | %(upload_date)s | https://youtu.be/%(id)s';
+const LOCAL_SEARCH_RATE_LIMIT_BACKOFF_MS = 1000;
+const LOCAL_SEARCH_RATE_LIMIT_MESSAGE =
+  'youtube rate-limited local search. do not use --paid as a fallback; retry later.';
+const LOCAL_SEARCH_RATE_LIMIT_RE = /429|too many requests|confirm you['\u2019]re not a bot/i;
+const LOCAL_SEARCH_CACHE_TTL_MS = 60 * 60 * 1000;
+const LOCAL_SEARCH_CACHE_FILE = 'youtube-search-cache.json';
+const LOCAL_SEARCH_CACHE_NOTE =
+  'cached because youtube rate-limited local search.';
+
+function showYoutubeSearchHelp(output = console.log, commandName = 'atris youtube') {
+  output('');
+  output(`Usage: ${commandName} search "<query>" [--limit N] [--json]`);
+  output(`       ${commandName} search --paid "<query>" [--limit N] [--json]`);
+  output('');
+  output('Free local discovery. Uses ytsearch on PATH when present, else the');
+  output('bundled scripts/det/ytsearch, else yt-dlp ytsearchN with the same print contract.');
+  output('Does not bill credits. Process stays the 5-credit step after you pick a URL.');
+  output('');
+  output(`--paid buys watch permalinks from Atris (${PAID_SEARCH_COST_HINT}).`);
+  output('Requires login. Same auth path as atris youtube process.');
+  output('Empty or failed paid search refunds the credits.');
+  output('');
+  output('Options:');
+  output(`  --limit <n>         Max results (default: ${DEFAULT_SEARCH_LIMIT})`);
+  output('  --paid              Bill credits for watch permalinks + titles');
+  output('  --json              Print JSON rows instead of pipe lines');
+  output('  -h, --help          This help');
+  output('');
+  output('Each free line:');
+  output('  title | channel | duration | views | upload_date | https://youtu.be/ID');
+  output('');
+  output('Each paid line:');
+  output('  title | https://www.youtube.com/watch?v=ID');
+  output('');
+  output('Examples:');
+  output(`  ${commandName} search "MCP agents 2026"`);
+  output(`  ${commandName} search "MCP agents" --limit 10`);
+  output(`  ${commandName} search "MCP agents" --json`);
+  output(`  ${commandName} search --paid "MCP agents 2026"`);
+  output(`  ${commandName} search --paid "MCP agents" --limit 10`);
+  output('');
+}
+
+function parseSearchArgs(argv = []) {
+  const args = [...argv];
+  const options = {
+    help: false,
+    json: false,
+    paid: false,
+    query: null,
+    limit: DEFAULT_SEARCH_LIMIT,
+    timeoutMs: PAID_SEARCH_TIMEOUT_MS,
+  };
+
+  if (args.length === 0 || ['help', '--help', '-h'].includes(args[0])) {
+    options.help = true;
+    return options;
+  }
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === '--help' || arg === '-h' || arg === 'help') {
+      options.help = true;
+    } else if (arg === '--json') {
+      options.json = true;
+    } else if (arg === '--paid') {
+      options.paid = true;
+    } else if (arg === '--limit') {
+      options.limit = parsePositiveSearchInt(readValue(args, i, arg), '--limit');
+      i++;
+    } else if (arg.startsWith('--limit=')) {
+      options.limit = parsePositiveSearchInt(arg.slice('--limit='.length), '--limit');
+    } else if (arg.startsWith('-')) {
+      throw new Error(`Unknown option: ${arg}`);
+    } else if (!options.query) {
+      options.query = arg;
+    } else {
+      throw new Error(`Unexpected argument: ${arg}`);
+    }
+  }
+
+  if (options.help) return options;
+  if (!options.query) throw new Error('Missing query. Run "atris youtube search --help".');
+  return options;
+}
+
+function parsePositiveSearchInt(raw, name) {
+  const value = Number(raw);
+  if (!Number.isInteger(value) || value <= 0) {
+    throw new Error(`${name} must be a positive integer`);
+  }
+  return value;
+}
+
+function parseSearchStdout(stdout = '') {
+  const rows = [];
+  for (const line of String(stdout || '').split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (!trimmed || !trimmed.includes('|')) continue;
+    const parts = trimmed.split(/\s*\|\s*/).map((part) => part.trim());
+    if (parts.length < 5) continue;
+    const url = parts[parts.length - 1];
+    if (!/^https?:\/\/(?:www\.)?(?:youtube\.com\/|youtu\.be\/)/i.test(url)) continue;
+    const row = {
+      title: parts[0] || '',
+      channel: parts[1] || '',
+      duration: parts[2] || '',
+      views: parts[3] || '',
+      url,
+    };
+    if (parts.length >= 6) {
+      const maybeDate = parts[parts.length - 2];
+      if (/^\d{8}$/.test(maybeDate) || maybeDate === 'NA' || maybeDate === 'None') {
+        row.upload_date = maybeDate === 'None' ? 'NA' : maybeDate;
+      }
+    }
+    rows.push(row);
+  }
+  return rows;
+}
+
+function formatSearchResults(rows = []) {
+  return rows.map((row) => {
+    const parts = [row.title, row.channel, row.duration, row.views];
+    if (row.upload_date) parts.push(row.upload_date);
+    parts.push(row.url);
+    return parts.join(' | ');
+  }).join('\n');
+}
+
+function normalizeSearchQuery(query) {
+  return String(query || '').trim().toLowerCase().replace(/\s+/g, ' ');
+}
+
+function searchCacheNow(deps = {}) {
+  if (typeof deps.now === 'function') return Number(deps.now());
+  return Date.now();
+}
+
+function searchCacheTtlMs(deps = {}) {
+  const ttl = Number(deps.searchCacheTtlMs);
+  return Number.isFinite(ttl) && ttl > 0 ? ttl : LOCAL_SEARCH_CACHE_TTL_MS;
+}
+
+function resolveSearchCachePath(deps = {}) {
+  if (deps.searchCachePath) return deps.searchCachePath;
+  const homeDir = deps.homeDir || os.homedir();
+  return path.join(homeDir, '.atris', LOCAL_SEARCH_CACHE_FILE);
+}
+
+function printSearchRows(rows, options, output) {
+  if (options.json) {
+    output(JSON.stringify(rows, null, 2));
+    return;
+  }
+  output(formatSearchResults(rows));
+}
+
+function writeLocalSearchCache(query, rows, deps = {}) {
+  if (!Array.isArray(rows) || !rows.length) return;
+  const fsMod = deps.fs || fs;
+  const filePath = resolveSearchCachePath(deps);
+  try {
+    if (typeof fsMod.mkdirSync === 'function') {
+      fsMod.mkdirSync(path.dirname(filePath), { recursive: true });
+    }
+    const payload = {
+      query: String(query || ''),
+      savedAt: searchCacheNow(deps),
+      rows,
+    };
+    fsMod.writeFileSync(filePath, `${JSON.stringify(payload)}\n`);
+  } catch {
+    // cache write is best-effort; a live search already succeeded
+  }
+}
+
+function readFreshLocalSearchCache(query, deps = {}) {
+  const fsMod = deps.fs || fs;
+  const filePath = resolveSearchCachePath(deps);
+  try {
+    const parsed = JSON.parse(fsMod.readFileSync(filePath, 'utf8'));
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return null;
+    if (normalizeSearchQuery(parsed.query) !== normalizeSearchQuery(query)) return null;
+    const savedAt = Number(parsed.savedAt);
+    if (!Number.isFinite(savedAt)) return null;
+    if (searchCacheNow(deps) - savedAt >= searchCacheTtlMs(deps)) return null;
+    if (!Array.isArray(parsed.rows) || !parsed.rows.length) return null;
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+function paidSearchPayload(options) {
+  const payload = { query: options.query };
+  if (options.limit != null) payload.limit = options.limit;
+  return payload;
+}
+
+function unwrapSearchPayload(data) {
+  if (data?.data && typeof data.data === 'object' && !Array.isArray(data.data)) {
+    return data.data;
+  }
+  return data && typeof data === 'object' ? data : {};
+}
+
+function watchPermalink(item = {}) {
+  const raw = item.url || item.permalink || item.watch_url || item.link || '';
+  if (typeof raw === 'string' && /^https?:\/\//i.test(raw)) return raw;
+  const id = item.video_id || item.videoId || (typeof item.id === 'string' ? item.id : '');
+  if (id && /^[A-Za-z0-9_-]{6,}$/.test(id)) {
+    return `https://www.youtube.com/watch?v=${id}`;
+  }
+  return '';
+}
+
+function paidSearchVideos(data) {
+  const payload = unwrapSearchPayload(data);
+  const raw = payload.results || payload.videos || payload.items
+    || (Array.isArray(data?.data) ? data.data : null)
+    || (Array.isArray(data) ? data : []);
+  if (!Array.isArray(raw)) return [];
+  const rows = [];
+  for (const item of raw) {
+    if (!item || typeof item !== 'object') continue;
+    const url = watchPermalink(item);
+    if (!url) continue;
+    rows.push({
+      title: String(item.title || item.name || '').trim(),
+      url,
+    });
+  }
+  return rows;
+}
+
+function creditsLine(data) {
+  const payload = unwrapSearchPayload(data);
+  const used = data?.credits_used !== undefined ? data.credits_used : payload.credits_used;
+  const remaining = data?.credits_remaining !== undefined
+    ? data.credits_remaining
+    : payload.credits_remaining;
+  if (used === undefined && remaining === undefined) return '';
+  return `Credits: ${used !== undefined ? used : '?'} used, ${remaining !== undefined ? remaining : '?'} remaining`;
+}
+
+function formatPaidSearchResults(data) {
+  const lines = paidSearchVideos(data).map((row) => (
+    row.title ? `${row.title} | ${row.url}` : row.url
+  ));
+  const credits = creditsLine(data);
+  if (credits) {
+    if (lines.length) lines.push('');
+    lines.push(credits);
+  }
+  return lines.join('\n');
+}
+
+function youtubeSearchFailureError(result) {
+  const hint = result.status === 401
+    ? ' Run "atris login --force".'
+    : result.status === 402
+      ? ' Check Atris credits.'
+      : result.status === 502
+        ? ' YouTube search is unavailable; retry in a few seconds.'
+        : '';
+  return new Error(`YouTube search failed (${result.status}): ${resultErrorText(result)}.${hint}`);
+}
+
+async function requestPaidYoutubeSearch(options, deps = {}) {
+  const apiFn = deps.apiRequestJson || apiRequestJson;
+  const ensureBilled = deps.ensureBilledCommandAuth || ensureBilledCommandAuth;
+  let auth = await ensureBilled('youtube', deps);
+  if (!auth?.ok || !auth.token) {
+    throw new Error(auth?.error || 'not signed in. run atris login first.');
+  }
+
+  const body = paidSearchPayload(options);
+  const call = (token) => apiFn('/youtube/search', {
+    method: 'POST',
+    token,
+    timeoutMs: options.timeoutMs || PAID_SEARCH_TIMEOUT_MS,
+    retries: 0,
+    body,
+  });
+
+  let result = await call(auth.token);
+  if (!result.ok && result.status === 401 && !auth.minted) {
+    const remint = await ensureBilled('youtube', { ...deps, forceMint: true });
+    if (remint?.ok && remint.token) {
+      auth = remint;
+      result = await call(auth.token);
+    }
+  }
+
+  if (!result.ok) {
+    throw youtubeSearchFailureError(result);
+  }
+  return result.data;
+}
+
+async function runPaidYoutubeSearch(options, deps = {}) {
+  const output = deps.output || ((line = '') => console.log(line));
+  const data = await requestPaidYoutubeSearch(options, deps);
+  if (options.json) {
+    output(JSON.stringify(data, null, 2));
+    return 0;
+  }
+
+  const videos = paidSearchVideos(data);
+  const rendered = formatPaidSearchResults(data);
+  if (!videos.length) {
+    output(rendered ? `no videos found\n${rendered}` : 'no videos found');
+    return 2;
+  }
+  output(rendered);
+  return 0;
+}
+
+function commandOnPath(name, deps = {}) {
+  const spawn = deps.spawnSync || spawnSync;
+  const result = spawn('sh', ['-c', `command -v ${shellSingleQuote(name)}`], {
+    encoding: 'utf8',
+    timeout: 5000,
+  });
+  if (result.error || result.status !== 0) return null;
+  const found = String(result.stdout || '').trim();
+  return found || null;
+}
+
+function shellSingleQuote(value) {
+  return `'${String(value).replace(/'/g, `'\\''`)}'`;
+}
+
+function bundledYtsearchPath() {
+  return path.join(__dirname, '..', 'scripts', 'det', 'ytsearch');
+}
+
+function defaultSearchRunner(query, limit, deps = {}) {
+  const spawn = deps.spawnSync || spawnSync;
+  const options = {
+    encoding: 'utf8',
+    timeout: 60000,
+    maxBuffer: 2 * 1024 * 1024,
+  };
+
+  const pathBin = deps.ytsearchBin || commandOnPath('ytsearch', deps);
+  if (pathBin) {
+    const result = spawn(pathBin, [query, String(limit)], options);
+    if (!(result.error && result.error.code === 'ENOENT')) return result;
+  }
+
+  const bundled = deps.bundledYtsearch || bundledYtsearchPath();
+  if (fs.existsSync(bundled)) {
+    const result = spawn(bundled, [query, String(limit)], options);
+    if (!(result.error && result.error.code === 'ENOENT')) return result;
+  }
+
+  return spawn('yt-dlp', [
+    '--no-update',
+    '--flat-playlist',
+    '--no-warnings',
+    '--print',
+    SEARCH_PRINT_FORMAT,
+    `ytsearch${limit}:${query}`,
+  ], options);
+}
+
+function searchRunnerDetail(result) {
+  return String(
+    (result && result.stderr) || (result && result.error && result.error.message) || 'search failed',
+  ).trim();
+}
+
+function isLocalSearchRateLimited(result) {
+  return LOCAL_SEARCH_RATE_LIMIT_RE.test(searchRunnerDetail(result));
+}
+
+function searchRunnerStatus(result) {
+  if (result && typeof result === 'object' && 'status' in result) return result.status;
+  return typeof result === 'number' ? result : 0;
+}
+
+async function waitLocalSearchBackoff(deps = {}) {
+  const ms = Number.isFinite(Number(deps.rateLimitBackoffMs))
+    ? Number(deps.rateLimitBackoffMs)
+    : LOCAL_SEARCH_RATE_LIMIT_BACKOFF_MS;
+  if (!(ms > 0)) return;
+  if (typeof deps.sleep === 'function') return deps.sleep(ms);
+  await new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function isMissingSearchBinary(result) {
+  return Boolean(result && typeof result === 'object' && result.error && result.error.code === 'ENOENT');
+}
+
+async function runYoutubeSearch(args = [], deps = {}) {
+  const output = deps.output || ((line = '') => console.log(line));
+  let options;
+  try {
+    options = parseSearchArgs(args);
+  } catch (err) {
+    output(err.message);
+    output(YTSEARCH_USAGE);
+    return 2;
+  }
+
+  if (options.help) {
+    showYoutubeSearchHelp(output, deps.commandName || 'atris youtube');
+    return 0;
+  }
+
+  if (options.paid) {
+    try {
+      return await runPaidYoutubeSearch(options, deps);
+    } catch (err) {
+      output(err.message);
+      return 1;
+    }
+  }
+
+  const runner = deps.runner || ((query, limit) => defaultSearchRunner(query, limit, deps));
+  let result;
+  try {
+    result = await Promise.resolve(runner(options.query, options.limit, deps));
+  } catch (err) {
+    output(String(err.message || err));
+    return 1;
+  }
+
+  if (isMissingSearchBinary(result)) {
+    output('ytsearch and yt-dlp not found. Install yt-dlp or put ytsearch on PATH.');
+    return 2;
+  }
+
+  let status = searchRunnerStatus(result);
+  if (status != null && status !== 0 && isLocalSearchRateLimited(result)) {
+    await waitLocalSearchBackoff(deps);
+    try {
+      result = await Promise.resolve(runner(options.query, options.limit, deps));
+    } catch (err) {
+      output(String(err.message || err));
+      return 1;
+    }
+    if (isMissingSearchBinary(result)) {
+      output('ytsearch and yt-dlp not found. Install yt-dlp or put ytsearch on PATH.');
+      return 2;
+    }
+    status = searchRunnerStatus(result);
+    if (status != null && status !== 0 && isLocalSearchRateLimited(result)) {
+      const cached = readFreshLocalSearchCache(options.query, deps);
+      if (cached) {
+        const rows = cached.rows.slice(0, options.limit);
+        printSearchRows(rows, options, output);
+        output(LOCAL_SEARCH_CACHE_NOTE);
+        return 0;
+      }
+      output(LOCAL_SEARCH_RATE_LIMIT_MESSAGE);
+      return status == null ? 1 : status;
+    }
+  }
+
+  if (status != null && status !== 0) {
+    const detail = searchRunnerDetail(result);
+    output(detail || 'search failed');
+    return status == null ? 1 : status;
+  }
+
+  const stdout = typeof result === 'string' ? result : String((result && result.stdout) || '');
+  const rows = parseSearchStdout(stdout);
+  if (!rows.length) {
+    output('no videos found');
+    return 2;
+  }
+
+  writeLocalSearchCache(options.query, rows, deps);
+  printSearchRows(rows, options, output);
+  return 0;
+}
+
 async function youtubeCommand(argv = process.argv.slice(3), deps = {}) {
   const output = deps.output || ((line = '') => console.log(line));
+  if (argv[0] === 'search') {
+    const code = await runYoutubeSearch(argv.slice(1), { ...deps, output });
+    if (!deps.output && !deps.spawnSync && !deps.runner && !deps.apiRequestJson && !deps.ensureValidCredentials && !deps.ensureBilledCommandAuth) {
+      process.exit(code);
+    }
+    return code;
+  }
   if (argv[0] === 'notes') {
     const code = runYoutubeNotes(argv.slice(1), deps);
     if (!deps.output && !deps.spawnSync && !deps.runner && !deps.expander) process.exit(code);
@@ -1248,9 +1762,18 @@ async function youtubeCommand(argv = process.argv.slice(3), deps = {}) {
     showYoutubeHelp(output, deps.commandName || 'atris youtube');
     return 0;
   }
-  const data = await processYoutube(options, deps);
-  output(options.json ? JSON.stringify(data, null, 2) : formatYoutubeResult(data));
-  return 0;
+  let status = 0;
+  try {
+    const data = await processYoutube(options, deps);
+    output(options.json ? JSON.stringify(data, null, 2) : formatYoutubeResult(data));
+  } catch (err) {
+    output(err.message);
+    status = 1;
+  }
+  if (!deps.output && !deps.apiRequestJson && !deps.ensureValidCredentials && !deps.ensureBilledCommandAuth && !deps.extractLocalTranscript) {
+    process.exit(status);
+  }
+  return status;
 }
 
 module.exports = {
@@ -1275,5 +1798,8 @@ module.exports = {
   parseFlatPlaylist,
   loadWatchState,
   watchCommand,
+  parseSearchArgs,
+  parseSearchStdout,
+  formatSearchResults,
   youtubeCommand,
 };

package/lib/account-bound.js

@@ -0,0 +1,47 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const ACCOUNT_GLOBAL_MESSAGE = 'account-global; pass --account to continue';
+
+function isBoundBusinessWorkspace(cwd = process.cwd()) {
+  const root = path.resolve(cwd);
+  return fs.existsSync(path.join(root, '.atris', 'business.json'))
+    && fs.existsSync(path.join(root, 'atris'));
+}
+
+function isHelpArg(arg) {
+  return arg === '--help' || arg === '-h' || arg === 'help';
+}
+
+/**
+ * Account-scoped verbs dump live CRM/cloud state. Outside a bound business
+ * workspace they must opt in with --account. Help always passes.
+ * Returns { ok, args } where args has --account stripped when continuing.
+ */
+function requireAccountBound(args = [], options = {}) {
+  const list = Array.isArray(args) ? [...args] : [];
+  const cwd = options.cwd || process.cwd();
+  if (list.some(isHelpArg)) {
+    return { ok: true, args: list, help: true };
+  }
+  if (isBoundBusinessWorkspace(cwd)) {
+    return { ok: true, args: list.filter((arg) => arg !== '--account'), bound: true };
+  }
+  if (list.includes('--account')) {
+    return { ok: true, args: list.filter((arg) => arg !== '--account'), account: true };
+  }
+  return { ok: false, args: list, message: ACCOUNT_GLOBAL_MESSAGE };
+}
+
+function refuseAccountGlobal(write = console.error) {
+  write(ACCOUNT_GLOBAL_MESSAGE);
+  return 2;
+}
+
+module.exports = {
+  ACCOUNT_GLOBAL_MESSAGE,
+  requireAccountBound,
+  refuseAccountGlobal,
+};