backdraw 0.0.0-stage → 2.1.0

package/platform/win32.js

@@ -0,0 +1,268 @@
+'use strict';
+// Windows implementation: named pipe, native host registration for each Chromium browser
+// (registry), user folders, installed browsers, and where the Claude Code CLI, the Claude desktop
+// app and their configs live.
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { execFileSync, spawn } = require('child_process');
+const identity = require('../identity');
+const browsers = require('../lib/browsers');
+
+const USER_TAG = (os.userInfo().username || 'user').replace(/[^A-Za-z0-9_.-]/g, '_');
+
+function pipePath() {
+  return `\\\\.\\pipe\\${identity.PIPE_PREFIX}-${USER_TAG}`;
+}
+
+// In the home folder, not under AppData: the Claude desktop app is an MSIX package, and AppData
+// writes made from its processes are redirected into the package's private storage, where Chrome
+// can't see them. The home folder itself is not redirected.
+// home: the user's home folder; install.js passes it so its tests can use a temporary one.
+function installDir(home = os.homedir()) {
+  return path.join(home, identity.INSTALL_DIR_NAME);
+}
+
+function legacyInstallDir(home = os.homedir()) {
+  return path.join(home, ...identity.LEGACY.INSTALL_DIR);
+}
+
+function claudeConfigFile(home = os.homedir()) {
+  return path.join(home, '.claude.json');
+}
+
+// Chat MCP config of the Claude desktop app: the MSIX package's private copy and the classic one.
+function desktopConfigFiles() {
+  const files = [];
+  const packages = path.join(process.env.LOCALAPPDATA || path.join(os.homedir(), 'AppData', 'Local'), 'Packages');
+  try {
+    for (const dir of fs.readdirSync(packages)) {
+      if (/^Claude_/i.test(dir)) files.push(path.join(packages, dir, 'LocalCache', 'Roaming', 'Claude', 'claude_desktop_config.json'));
+    }
+  } catch {}
+  files.push(path.join(process.env.APPDATA || path.join(os.homedir(), 'AppData', 'Roaming'), 'Claude', 'claude_desktop_config.json'));
+  return files.filter(f => fs.existsSync(f));
+}
+
+// Reads the output of the process query below: one executable path per line, '?' when a path
+// can't be read. Claude Code's own claude.exe has the same process name but lives elsewhere and
+// doesn't count; an unreadable path counts as the desktop app, to be safe.
+function parseClaudeProcesses(out) {
+  return String(out || '').split(/\r?\n/).map(s => s.trim()).filter(Boolean)
+    .some(p => p === '?' || /\\WindowsApps\\|\\AnthropicClaude\\/i.test(p));
+}
+
+// True while the Claude desktop app runs (it rewrites its config on exit), false when it doesn't,
+// null when that can't be told (PowerShell failed). With no claude process Get-Process reports an
+// error even when silenced, so the script collects the result and exits 0 explicitly.
+function desktopAppRunning() {
+  let out;
+  try {
+    out = execFileSync('powershell.exe', ['-NoProfile', '-NonInteractive', '-Command',
+      "[Console]::OutputEncoding = [Text.Encoding]::UTF8; $p = @(Get-Process -Name claude -ErrorAction SilentlyContinue | ForEach-Object { if ($_.Path) { $_.Path } else { '?' } }); $p; exit 0"],
+    { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+  } catch {
+    return null;
+  }
+  return parseClaudeProcesses(out);
+}
+
+// key: an id of browsers.HOST_KEYS (chrome, edge, chromium); Chrome's when left out.
+const regSubkey = (hostName, key = 'chrome') => `${browsers.HOST_KEYS[key]}\\${hostName}`;
+const regKey = (hostName, key) => `HKCU\\${regSubkey(hostName, key)}`;
+
+// Same MSIX caveat for the registry: HKCU writes from inside the package go to a private copy.
+// WMI's registry provider runs outside the package, so it writes the HKCU that Chrome reads.
+function realRegistry(subkey, action, value = '') {
+  const ps = `$ErrorActionPreference = 'Stop'
+$hk = [uint32]2147483649
+$k = '${subkey}'
+function Reg($m, $a) { Invoke-CimMethod -Namespace root/default -ClassName StdRegProv -MethodName $m -Arguments $a }
+if ('${action}' -eq 'delete') { [void](Reg 'DeleteKey' @{ hDefKey = $hk; sSubKeyName = $k }); exit 0 }
+[void](Reg 'CreateKey' @{ hDefKey = $hk; sSubKeyName = $k })
+$r = Reg 'SetStringValue' @{ hDefKey = $hk; sSubKeyName = $k; sValueName = ''; sValue = $env:BACKDRAW_VALUE }
+if ($r.ReturnValue -ne 0) { throw "SetStringValue returned $($r.ReturnValue)" }
+(Reg 'GetStringValue' @{ hDefKey = $hk; sSubKeyName = $k; sValueName = '' }).sValue`;
+  return execFileSync('powershell.exe', ['-NoProfile', '-NonInteractive', '-Command', ps],
+    { encoding: 'utf8', env: { ...process.env, BACKDRAW_VALUE: value } }).trim();
+}
+
+// Chrome starts the host through this launcher when the extension connects (native messaging).
+function writeHostLauncher(dir, nodePath) {
+  const bat = path.join(dir, 'host.bat');
+  fs.writeFileSync(bat, `@echo off\r\n"${nodePath}" "%~dp0host.js" %*\r\n`);
+  return bat;
+}
+
+// Returns where the registration lives, for display.
+function registerNativeHost(hostName, manifestPath, key = 'chrome') {
+  const full = regKey(hostName, key);
+  try { execFileSync('reg.exe', ['delete', full, '/f'], { stdio: 'ignore' }); } catch {} // stale private copy, if any
+  try {
+    if (realRegistry(regSubkey(hostName, key), 'set', manifestPath) === manifestPath) return full;
+  } catch {}
+  execFileSync('reg.exe', ['add', full, '/ve', '/t', 'REG_SZ', '/d', manifestPath, '/f'], { stdio: 'ignore' });
+  return full;
+}
+
+// Where a host's registration lives, for display (e.g. the uninstall dry run).
+function nativeHostEntry(hostName, key = 'chrome') {
+  return regKey(hostName, key);
+}
+
+function unregisterNativeHost(hostName, key = 'chrome') {
+  try { realRegistry(regSubkey(hostName, key), 'delete'); } catch {}
+  try { execFileSync('reg.exe', ['delete', regKey(hostName, key), '/f'], { stdio: 'ignore' }); } catch {}
+}
+
+// For `backdraw doctor`: in one PowerShell run, through WMI (the real registry, also from inside an
+// MSIX package), the registration of `hostName` under every host key, and each browser's native
+// messaging policies from HKLM and HKCU (lists are policy subkeys with numbered string values).
+// Returns the raw JSON text; parseBrowserRegistry() reads it.
+function readBrowserRegistry(hostName) {
+  const query = {
+    hosts: Object.keys(browsers.HOST_KEYS).map(id => ({ id, key: regSubkey(hostName, id) })),
+    policies: browsers.BROWSERS.map(b => ({ id: b.id, policyKey: b.policyKey })),
+  };
+  const ps = `$ErrorActionPreference = 'Stop'
+[Console]::OutputEncoding = [Text.Encoding]::UTF8
+function Reg($m, $a) { Invoke-CimMethod -Namespace root/default -ClassName StdRegProv -MethodName $m -Arguments $a }
+$hives = @(@('hklm', [uint32]2147483650), @('hkcu', [uint32]2147483649))
+$q = $env:BACKDRAW_QUERY | ConvertFrom-Json
+$hosts = @{}
+foreach ($h in $q.hosts) { $hosts[$h.id] = (Reg 'GetStringValue' @{ hDefKey = [uint32]2147483649; sSubKeyName = $h.key; sValueName = '' }).sValue }
+$policies = @{}
+foreach ($b in $q.policies) {
+  $policy = @{}
+  foreach ($h in $hives) {
+    $d = Reg 'GetDWORDValue' @{ hDefKey = $h[1]; sSubKeyName = $b.policyKey; sValueName = 'NativeMessagingUserLevelHosts' }
+    $p = @{ userLevelHosts = $(if ($d.ReturnValue -eq 0) { [int]$d.uValue } else { $null }) }
+    foreach ($l in 'NativeMessagingBlocklist', 'NativeMessagingAllowlist') {
+      $sub = "$($b.policyKey)\\$l"
+      $e = Reg 'EnumValues' @{ hDefKey = $h[1]; sSubKeyName = $sub }
+      $vals = @()
+      if ($e.ReturnValue -eq 0 -and $e.sNames) { foreach ($n in $e.sNames) { $vals += [string](Reg 'GetStringValue' @{ hDefKey = $h[1]; sSubKeyName = $sub; sValueName = $n }).sValue } }
+      $p[$l] = $vals
+    }
+    $policy[$h[0]] = $p
+  }
+  $policies[$b.id] = $policy
+}
+ConvertTo-Json -InputObject @{ hosts = $hosts; policies = $policies } -Depth 6 -Compress`;
+  return execFileSync('powershell.exe', ['-NoProfile', '-NonInteractive', '-Command', ps],
+    { encoding: 'utf8', env: { ...process.env, BACKDRAW_QUERY: JSON.stringify(query) }, stdio: ['ignore', 'pipe', 'ignore'] });
+}
+
+// { hosts: { chrome: manifest path or null, edge, chromium },
+//   policies: { <browser id>: { userLevelHosts, blocklist, allowlist } } }.
+// A machine (HKLM) policy wins over the same user (HKCU) policy.
+function parseBrowserRegistry(text) {
+  const raw = JSON.parse(String(text).replace(/^\uFEFF/, '').trim() || '{}');
+  const list = v => [].concat(v === null || v === undefined ? [] : v).map(String);
+  const hosts = {};
+  for (const id of Object.keys(browsers.HOST_KEYS)) hosts[id] = (raw.hosts || {})[id] || null;
+  const policies = {};
+  for (const [id, policy] of Object.entries(raw.policies || {})) {
+    const pick = (name, read) => {
+      for (const hive of ['hklm', 'hkcu']) {
+        const v = read(((policy || {})[hive] || {})[name]);
+        if (v !== undefined) return v;
+      }
+      return undefined;
+    };
+    policies[id] = {
+      userLevelHosts: pick('userLevelHosts', v => (v === null || v === undefined ? undefined : Number(v) !== 0)),
+      blocklist: pick('NativeMessagingBlocklist', v => (list(v).length ? list(v) : undefined)) || [],
+      allowlist: pick('NativeMessagingAllowlist', v => (list(v).length ? list(v) : undefined)) || [],
+    };
+  }
+  return { hosts, policies };
+}
+
+// Program Files, Program Files (x86) and LocalAppData: where browsers install themselves.
+function programRoots() {
+  const env = process.env;
+  return [env.ProgramFiles || 'C:\\Program Files', env['ProgramFiles(x86)'] || 'C:\\Program Files (x86)',
+    env.LOCALAPPDATA || path.join(os.homedir(), 'AppData', 'Local')];
+}
+
+// The executable of a browser (its first channel that is there), or null when it isn't installed.
+function browserExe(browser) {
+  for (const rel of browsers.byId(browser).exe) {
+    for (const root of programRoots()) {
+      const exe = path.join(root, rel);
+      if (fs.existsSync(exe)) return exe;
+    }
+  }
+  return null;
+}
+
+function detectBrowsers() {
+  return browsers.BROWSERS.filter(b => browserExe(b.id)).map(b => b.id);
+}
+
+// Opens a browser page (e.g. its extensions page) in that browser, if it is installed.
+function openInBrowser(browser, url) {
+  const exe = browserExe(browser);
+  if (!exe) return false;
+  const child = spawn(exe, [url], { detached: true, stdio: 'ignore' });
+  child.on('error', () => {});
+  child.unref();
+  return true;
+}
+
+function openFolder(dir) {
+  const child = spawn('explorer.exe', [dir], { detached: true, stdio: 'ignore' });
+  child.on('error', () => {});
+  child.unref();
+}
+
+// Through PowerShell (clip.exe mangles non-ASCII paths). Returns whether it worked.
+function copyToClipboard(text) {
+  try {
+    execFileSync('powershell.exe', ['-NoProfile', '-NonInteractive', '-Command', 'Set-Clipboard -Value $env:BACKDRAW_CLIP'],
+      { stdio: 'ignore', env: { ...process.env, BACKDRAW_CLIP: text } });
+    return true;
+  } catch { return false; }
+}
+
+// The first match of a command on PATH, or null.
+function which(cmd) {
+  try { return execFileSync('where.exe', [cmd], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).split(/\r?\n/)[0].trim() || null; } catch { return null; }
+}
+
+function appDataDir() {
+  return process.env.APPDATA || path.join(os.homedir(), 'AppData', 'Roaming');
+}
+
+function picturesDir() {
+  try {
+    const out = execFileSync('powershell.exe', ['-NoProfile', '-Command',
+      "[Console]::OutputEncoding = [Text.Encoding]::UTF8; [Environment]::GetFolderPath('MyPictures')"], { encoding: 'utf8' }).trim();
+    if (out && fs.existsSync(out)) return out;
+  } catch {}
+  return path.join(os.homedir(), 'Pictures');
+}
+
+function claudeCli() {
+  const local = path.join(os.homedir(), '.local', 'bin', 'claude.exe');
+  if (fs.existsSync(local)) return local;
+  return which('claude');
+}
+
+// Opens Explorer with the file selected. No shell: explorer.exe is started directly. Its own parser
+// splits "/select," arguments at commas, so the path is always quoted (a Windows path never holds ").
+function revealInFolder(file, run = spawn) {
+  if (typeof file !== 'string' || !path.win32.isAbsolute(file) || file.includes('"')) throw new Error('Not an absolute file path.');
+  const child = run('explorer.exe', ['/select,', `"${file}"`], { detached: true, stdio: 'ignore', windowsVerbatimArguments: true });
+  child.on('error', () => {});
+  child.unref();
+}
+
+module.exports = {
+  pipePath, installDir, legacyInstallDir, claudeConfigFile, desktopConfigFiles, desktopAppRunning, parseClaudeProcesses,
+  writeHostLauncher, registerNativeHost, unregisterNativeHost, nativeHostEntry, readBrowserRegistry, parseBrowserRegistry,
+  detectBrowsers, browserExe, openInBrowser, openFolder, copyToClipboard, which, appDataDir,
+  picturesDir, claudeCli,
+  revealInFolder,
+};

package/setup.js

@@ -0,0 +1,212 @@
+'use strict';
+// `backdraw setup` (npx backdraw@latest setup): installs Backdraw into %USERPROFILE%\.backdraw (npx's
+// own copy is temporary), registers the native host for the installed browsers, adds Backdraw to
+// the MCP clients the user picks, then walks through loading the extension and waits for it.
+//   --yes                 no questions: every client that was found
+//   --clients=a,b         exactly these (ids: see CLIENT_IDS)
+//   --browser=edge        the browser to load the extension in (default: the first one found)
+//   --no-wait             don't wait for the extension to connect
+const fs = require('fs');
+const path = require('path');
+const installer = require('./install');
+const browsers = require('./lib/browsers');
+const mcpClients = require('./lib/mcp-clients');
+const { useColor, painter, line } = require('./lib/term');
+
+const SELF = require('./package.json').version;
+const CLIENT_IDS = ['claude-code', 'claude-desktop', ...mcpClients.FILE_CLIENTS.map(c => c.id)];
+const WAIT_MS = 180000;
+const EXAMPLE = 'Generate an image with ChatGPT: a cozy reading nook by a rainy window, warm lamp light.';
+
+// Every client setup knows, and whether it is on this PC.
+function detectClients(c) {
+  const p = c.platform;
+  return [
+    { id: 'claude-code', label: 'Claude Code', detected: !!c.claudeCli || fs.existsSync(p.claudeConfigFile(c.home)) },
+    { id: 'claude-desktop', label: 'Claude desktop app', detected: p.desktopConfigFiles().length > 0 },
+    ...mcpClients.FILE_CLIENTS.map(client => ({ id: client.id, label: client.label, detected: client.detect(c.clientEnv) })),
+  ];
+}
+
+function parseClientList(value) {
+  if (value === true || value === '') throw new Error(`--clients needs a list, e.g. --clients=claude-code,cursor (one of: ${CLIENT_IDS.join(', ')}).`);
+  const ids = String(value).split(',').map(s => s.trim().toLowerCase()).filter(Boolean);
+  const unknown = ids.filter(id => !CLIENT_IDS.includes(id));
+  if (unknown.length) throw new Error(`Unknown client ${unknown.join(', ')}; use: ${CLIENT_IDS.join(', ')}.`);
+  return [...new Set(ids)];
+}
+
+// The answer to the client question: '' = the found ones, "none"/"0", or numbers like "1,3".
+// Returns the ids, or null for an answer that doesn't parse.
+function parseChoice(answer, found) {
+  const a = String(answer || '').trim().toLowerCase();
+  if (!a) return found.filter(f => f.detected).map(f => f.id);
+  if (a === 'none' || a === '0') return [];
+  const nums = a.split(/[\s,]+/).filter(Boolean).map(Number);
+  if (nums.some(n => !Number.isInteger(n) || n < 1 || n > found.length)) return null;
+  return [...new Set(nums.map(n => found[n - 1].id))];
+}
+
+async function chooseClients(found, ask, log) {
+  log('MCP clients on this PC:');
+  found.forEach((f, i) => log(`  ${i + 1}. ${f.label.padEnd(20)} ${f.detected ? 'found' : 'not found'}`));
+  const dflt = found.map((f, i) => (f.detected ? i + 1 : null)).filter(Boolean);
+  for (let tries = 0; tries < 3; tries++) {
+    const ids = parseChoice(await ask(`Add Backdraw to which? Enter = the found ones (${dflt.join(', ') || 'none'}), numbers like 1,3, or "none": `), found);
+    if (ids) return ids;
+    log(`Please answer with numbers from 1 to ${found.length}, or "none".`);
+  }
+  throw new Error('No valid answer; run setup again, or pass --clients=… or --yes.');
+}
+
+function addToDesktop(c, server) {
+  const p = c.platform;
+  const files = p.desktopConfigFiles();
+  if (!files.length) return [['warn', 'no Claude desktop config was found; start the app once, then run: npx backdraw@latest setup --clients=claude-desktop']];
+  const running = p.desktopAppRunning();
+  if (running !== false) {
+    return [['warn', `${running ? 'Claude is running' : 'couldn\'t tell whether Claude is running'}, so its config was left alone. Quit Claude completely (also from the system tray), then run: npx backdraw@latest setup --clients=claude-desktop`]];
+  }
+  return files.map(file => {
+    try {
+      const backup = installer.updateDesktopConfig(file, installer.desktopEntry(server));
+      return ['ok', backup ? `added (${file}; backup ${path.basename(backup)})` : 'already set up'];
+    } catch (e) { return ['fail', `${file}: ${e.message}`]; }
+  });
+}
+
+function addToFileClient(c, id, server) {
+  try {
+    const r = mcpClients.addEntry(mcpClients.byId(id), c.clientEnv, installer.NODE, server);
+    if (r.status === 'unchanged') return ['ok', `already set up (${r.file})`];
+    return ['ok', `${r.status} (${r.file}${r.backup ? `; backup ${path.basename(r.backup)}` : ''})`];
+  } catch (e) { return ['fail', e.message]; }
+}
+
+// Polls the bridge until the extension is connected (and, with `version`, runs that version).
+// Resolves to its status, or null on a timeout or when skipped (Ctrl+C).
+function waitForExtension(call, { timeoutMs = WAIT_MS, intervalMs = 2000, onSigint = true, version = null } = {}) {
+  return new Promise(resolve => {
+    let done = false;
+    let timer = null;
+    const finish = value => {
+      if (done) return;
+      done = true;
+      clearTimeout(timer);
+      if (onSigint) process.removeListener('SIGINT', skip);
+      resolve(value);
+    };
+    const skip = () => finish(null);
+    if (onSigint) process.on('SIGINT', skip);
+    const deadline = Date.now() + timeoutMs;
+    // A Ctrl+C can arrive while a call is still out: then nothing may poll again.
+    const poll = async () => {
+      if (done) return;
+      try {
+        const status = await call('status', {}, 3000);
+        if (status && status.extension && (!version || status.extension.version === version)) return finish(status);
+      } catch {}
+      if (done) return;
+      if (Date.now() >= deadline) return finish(null);
+      timer = setTimeout(poll, intervalMs);
+    };
+    poll();
+  });
+}
+
+async function connectedStatus(call) {
+  try {
+    const status = await call('status', {}, 3000);
+    return status && status.extension ? status : null;
+  } catch { return null; }
+}
+
+// deps (tests): ctx (install.js context), call (bridge), ask (question -> answer; none = no TTY),
+// log, color, waitMs.
+async function setup(opts = {}, deps = {}) {
+  const log = deps.log || (text => console.log(text));
+  const paint = painter(deps.color !== undefined ? deps.color : useColor());
+  const say = (status, label, detail) => log(line(paint, status, label, detail, 20));
+  const call = deps.call || require('./shared').call;
+  const base = { ...(deps.ctx || {}), report: false };
+  const c = installer.context(base);
+  const p = c.platform;
+
+  let browser = null;
+  if (opts.browser !== undefined) {
+    browser = browsers.byId(String(opts.browser).toLowerCase());
+    if (!browser) throw new Error(`--browser takes one of: ${browsers.BROWSERS.map(b => b.id).join(', ')}.`);
+  }
+
+  log(paint('bold', `Backdraw ${SELF} setup`));
+  log('');
+  const found = detectClients(c);
+  let chosen;
+  if (opts.clients !== undefined) chosen = parseClientList(opts.clients);
+  else if (opts.yes || !deps.ask) chosen = found.filter(f => f.detected).map(f => f.id);
+  else { chosen = await chooseClients(found, deps.ask, log); log(''); }
+
+  const r = await installer.install({ ...base, clients: chosen, browsers: browser ? [browser.id] : [] });
+  say('ok', 'Installed', `${r.dest} (${r.version})`);
+  for (const m of r.migration.filter(x => x.startsWith('copied '))) say('ok', 'Migrated', m.replace(/^copied /, ''));
+  if (r.hasLegacy) say('info', 'Old folder', `${r.legacyDir} is no longer used; delete it by hand once Backdraw works`);
+  say('ok', 'Native host', `registered for ${r.registered.map(b => browsers.byId(b).name).join(', ')}`);
+
+  const labels = Object.fromEntries(found.map(f => [f.id, f.label]));
+  for (const id of chosen) {
+    if (id === 'claude-code') say('ok', labels[id], 'added (user scope)');
+    else if (id === 'claude-desktop') for (const [status, detail] of addToDesktop(c, r.server)) say(status, labels[id], detail);
+    else {
+      const [status, detail] = addToFileClient(c, id, r.server);
+      say(status, labels[id], detail);
+    }
+  }
+  if (!chosen.length) say('warn', 'MCP clients', `none chosen; add one later with: npx backdraw@latest setup --clients=${CLIENT_IDS[0]}`);
+
+  // A reloaded extension needs a few seconds to start the new host; until then the old one may
+  // still answer with the old version.
+  let status = r.reloaded
+    ? await waitForExtension(call, { timeoutMs: deps.reloadWaitMs || 20000, intervalMs: deps.intervalMs || 1000, onSigint: false, version: r.version })
+      || await connectedStatus(call)
+    : await connectedStatus(call);
+  if (status && status.extension.version !== r.version) {
+    say('warn', 'Extension', `${status.extension.version} is still running; reload Backdraw at chrome://extensions to start ${r.version}`);
+  } else if (status) say('ok', 'Extension', `${status.extension.version} connected${r.reloaded ? ' (reloaded with the new files)' : ''}`);
+
+  if (!status) {
+    // The one named with --browser, else the first one installed (Chrome comes first).
+    if (!browser) browser = browsers.byId(p.detectBrowsers()[0] || 'chrome');
+    const folder = path.join(r.dest, 'extension');
+    try { p.openFolder(folder); } catch {}
+    const copied = p.copyToClipboard(folder);
+    const opened = p.openInBrowser(browser.id, browser.page);
+    log('');
+    log(paint('bold', `Load the extension in ${browser.name} (once):`));
+    log(`  1. ${opened ? `${browser.page} is opening; turn` : `Open ${browser.page} and turn`} on "Developer mode" (top right).`);
+    log('  2. Click "Load unpacked".');
+    log(`  3. Pick the folder ${folder}${copied ? ' (the path is on your clipboard: paste it with Ctrl+V)' : ''}.`);
+    if (opts.wait === false) {
+      log('');
+      say('info', 'Extension', 'not waiting (--no-wait); check later with: npx backdraw@latest doctor');
+    } else {
+      log('');
+      log(`Waiting for the extension to connect (up to ${Math.round((deps.waitMs || WAIT_MS) / 60000)} min; Ctrl+C skips)…`);
+      status = await waitForExtension(call, { timeoutMs: deps.waitMs || WAIT_MS, intervalMs: deps.intervalMs, onSigint: !deps.call });
+      if (status) say('ok', 'Extension', `${status.extension.version} connected`);
+      else say('warn', 'Extension', 'not connected yet; once it is loaded, check with: npx backdraw@latest doctor');
+    }
+  }
+
+  log('');
+  if (status) {
+    log(paint('ok', '✓ Ready.'));
+    if (!status.project) log('One more step: click the Backdraw icon in the toolbar and pick a ChatGPT Project (its checklist shows how).');
+  }
+  if (chosen.length) {
+    log('Start a new session in your MCP client (Backdraw is loaded when a session starts) and say:');
+    log(`  "${EXAMPLE}"`);
+  }
+  return { result: r, chosen, status };
+}
+
+module.exports = { CLIENT_IDS, detectClients, parseClientList, parseChoice, waitForExtension, setup };

package/shared.js

@@ -0,0 +1,118 @@
+'use strict';
+// Paths, small file helpers and the named-pipe client shared by the MCP server and the CLI.
+const fs = require('fs');
+const net = require('net');
+const path = require('path');
+const identity = require('./identity');
+const platform = require('./platform');
+const { MAX_REFS, MAX_REF_BYTES, MAX_REFS_TOTAL_BYTES } = require('./lib/limits');
+
+const ROOT = __dirname;
+// Single version source; install.js copies package.json next to these files.
+const VERSION = require('./package.json').version;
+const DATA_DIR = path.join(ROOT, 'data');
+const LOG_DIR = path.join(ROOT, 'logs');
+const CONFIG_FILE = path.join(DATA_DIR, 'config.json');
+const JOBS_FILE = path.join(DATA_DIR, 'jobs.json');
+const PREVIEW_DIR = path.join(DATA_DIR, 'previews');
+
+// Resolved on first use, so loading this module works on every OS. BACKDRAW_PIPE override: tests only.
+let pipePath = null;
+function getPipePath() { return pipePath || (pipePath = process.env[identity.PIPE_ENV] || platform.pipePath()); }
+
+const NOT_RUNNING =
+  'The ChatGPT bridge is not running: Google Chrome is closed, or the browser extension ' +
+  'is not loaded/enabled. Ask the user to open Chrome; the extension connects by itself.';
+
+function readJson(file, fallback) {
+  try { return JSON.parse(fs.readFileSync(file, 'utf8')); } catch { return fallback; }
+}
+
+function writeJson(file, value) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const tmp = `${file}.${process.pid}.tmp`;
+  fs.writeFileSync(tmp, JSON.stringify(value, null, 2));
+  fs.renameSync(tmp, file);
+}
+
+class BridgeError extends Error {
+  constructor(message, code) { super(message); this.code = code; }
+}
+
+// One request per connection: write a JSON line, read one JSON line back.
+function call(method, params = {}, timeoutMs = 30000) {
+  return new Promise((resolve, reject) => {
+    const sock = net.connect(getPipePath());
+    let buf = '';
+    let done = false;
+    const finish = (err, value) => {
+      if (done) return;
+      done = true;
+      clearTimeout(timer);
+      sock.destroy();
+      if (err) reject(err); else resolve(value);
+    };
+    const timer = setTimeout(
+      () => finish(new BridgeError(`The bridge did not answer "${method}" within ${Math.round(timeoutMs / 1000)}s.`, 'TIMEOUT')),
+      timeoutMs);
+    sock.setEncoding('utf8');
+    sock.on('connect', () => sock.write(JSON.stringify({ id: 1, method, params }) + '\n'));
+    sock.on('data', chunk => {
+      buf += chunk;
+      const nl = buf.indexOf('\n');
+      if (nl < 0) return;
+      let msg;
+      try { msg = JSON.parse(buf.slice(0, nl)); } catch (e) { return finish(e); }
+      if (msg.error) finish(new BridgeError(msg.error.message, msg.error.code));
+      else finish(null, msg.result);
+    });
+    sock.on('error', e => finish(['ENOENT', 'ECONNREFUSED', 'EPIPE'].includes(e.code) ? new BridgeError(NOT_RUNNING, 'NOT_RUNNING') : e));
+    sock.on('close', () => finish(new BridgeError('The bridge closed the connection unexpectedly.', 'CLOSED')));
+  });
+}
+
+const IMAGE_TYPES = { '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.webp': 'image/webp', '.gif': 'image/gif' };
+
+// Reads reference images in the caller's own context (relative paths = its working folder).
+function readReferences(list) {
+  if (!list) return [];
+  if (!Array.isArray(list)) list = [list];
+  if (list.length > MAX_REFS) throw new Error(`At most ${MAX_REFS} reference images per request.`);
+  let total = 0;
+  return list.map(p => {
+    const file = path.resolve(String(p));
+    const mime = IMAGE_TYPES[path.extname(file).toLowerCase()];
+    if (!mime) throw new Error(`Reference is not a png/jpg/webp/gif image: ${file}`);
+    let buf;
+    try { buf = fs.readFileSync(file); } catch (e) { throw new Error(`Cannot read reference image ${file} (${e.code || e.message}).`); }
+    if (buf.length > MAX_REF_BYTES) throw new Error(`Reference image is larger than ${MAX_REF_BYTES / 1048576} MB: ${file}`);
+    if ((total += buf.length) > MAX_REFS_TOTAL_BYTES) throw new Error(`The reference images together are larger than ${MAX_REFS_TOTAL_BYTES / 1048576} MB.`);
+    return { name: path.basename(file), mime, data: buf.toString('base64') };
+  });
+}
+
+// Copies a finished job's images into the folder the caller asked for (once), from the caller's
+// own process so the copy lands where the caller can see it.
+async function copyResults(job) {
+  if (job.status !== 'succeeded' || !job.copyTo || (job.copies && job.copies.length)) return job;
+  try {
+    fs.mkdirSync(job.copyTo, { recursive: true });
+    const copies = job.images.map(im => {
+      const ext = path.extname(im.path);
+      const base = path.basename(im.path, ext);
+      let dest = path.join(job.copyTo, `${base}${ext}`);
+      for (let n = 2; fs.existsSync(dest); n++) dest = path.join(job.copyTo, `${base}_${n}${ext}`);
+      fs.copyFileSync(im.path, dest);
+      return dest;
+    });
+    return await call('mark_copied', { jobId: job.id, paths: copies });
+  } catch (e) {
+    return { ...job, copyError: e.message };
+  }
+}
+
+module.exports = {
+  VERSION, ROOT, DATA_DIR, LOG_DIR, CONFIG_FILE, JOBS_FILE, PREVIEW_DIR,
+  NOT_RUNNING, BridgeError, readJson, writeJson, call, readReferences, copyResults,
+  get PIPE_PATH() { return getPipePath(); },
+};