chromeflow 0.8.0 → 0.9.9

package/dist/setup.js

@@ -1,493 +0,0 @@
-import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync } from "fs";
-import { homedir } from "os";
-import { join, resolve, dirname } from "path";
-import { fileURLToPath } from "url";
-import { execSync } from "child_process";
-const HOME = homedir();
-const CLAUDE_JSON_PATH = join(HOME, ".claude.json");
-function getClaudeMdContent() {
-  const packageDir = dirname(dirname(fileURLToPath(import.meta.url)));
-  const claudeMdPath = join(packageDir, "CLAUDE.md");
-  if (existsSync(claudeMdPath)) {
-    return readFileSync(claudeMdPath, "utf8");
-  }
-  const devPath = join(dirname(fileURLToPath(import.meta.url)), "..", "CLAUDE.md");
-  if (existsSync(devPath)) {
-    return readFileSync(devPath, "utf8");
-  }
-  throw new Error("CLAUDE.md not found in package. Run `npm run build` first.");
-}
-const PROJECT_CLAUDE_MD = `# Chromeflow \u2014 Claude Instructions
-
-## What chromeflow is
-Chromeflow is a browser guidance tool. When a task requires the user to interact with a
-website (create accounts, set up billing, retrieve API keys, configure third-party services),
-use chromeflow to guide them through it visually instead of giving text instructions.
-
-## When to use chromeflow (be proactive)
-Use chromeflow automatically whenever a task requires:
-- Creating or configuring a third-party account (Stripe, SendGrid, Supabase, Vercel, etc.)
-- Retrieving API keys, secrets, or credentials to place in \`.env\`
-- Setting up pricing tiers, webhooks, or service configuration in a web UI
-- Any browser-based step that is blocking code work
-
-Do NOT ask "should I open the browser?" \u2014 just do it. The user expects seamless handoff.
-
-## HARD RULES \u2014 never break these
-
-1. **Never use Bash as a fallback for browser tasks.** If \`click_element\` fails, use
-   \`scroll_page\` then retry, or use \`highlight_region\` to show the user. Never use
-   \`osascript\`, \`applescript\`, or any shell command to control the browser.
-
-2. **Take a screenshot only when you need to decide what to do next.** Do not take
-   a screenshot after every action as a reflex. Take one after navigation, or when
-   \`click_element\`/\`find_and_highlight\` fails and you need to locate something visually.
-
-3. **\`open_page\` already waits for navigation.** Never call \`wait_for_navigation\`
-   immediately after \`open_page\` \u2014 it will time out.
-
-4. **When \`click_element\` fails:** first try \`scroll_page(down)\` then retry
-   \`click_element\`. If it still fails, \`take_screenshot\` and use \`highlight_region\`
-   with pixel coordinates from the image.
-
-## Guided flow pattern
-
-\`\`\`
-1. open_page(url)                            \u2014 navigate to the right page
-2. For each step:
-   a. [if needed] take_screenshot()          \u2014 only when you need to locate something
-   b. Claude acts directly:
-        click_element("Save")               \u2014 press buttons/links Claude can press
-        fill_input("Product name", "Pro")   \u2014 fill fields Claude knows the answer to
-        scroll_page("down")                 \u2014 reveal off-screen content then retry
-      Or pause for the user:
-        find_and_highlight(text, msg)        \u2014 show the user what to do
-        wait_for_click()                    \u2014 wait for user interaction
-3. clear_overlays()                          \u2014 clean up when done
-\`\`\`
-
-**Default to automation.** Only pause for human input when the step genuinely requires
-personal data or a human decision.
-
-## What to do automatically vs pause for the user
-
-**Claude acts directly** (\`click_element\` / \`fill_input\`):
-- Any button: Save, Continue, Create, Add, Confirm, Next, Submit, Update
-- Product names, descriptions, feature lists
-- Prices and amounts specified in the task
-- URLs, redirect URIs, webhook endpoints
-- Selecting billing period, currency, or other known options
-- Dismissing cookie banners, cookie dialogs, "not now" prompts
-
-**Pause for the user** (\`find_and_highlight\` + \`wait_for_click\`):
-- Email address / username / login
-- Password or passphrase
-- Payment method / billing / card details
-- Phone number / 2FA / OTP codes
-- Any legal consent the user must personally accept
-- Choices that depend on user preference Claude wasn't told
-
-## Capturing credentials
-After a secret key or API key is revealed:
-1. \`read_element(hint)\` \u2014 capture the value
-2. \`write_to_env(KEY_NAME, value, envPath)\` \u2014 write to \`.env\`
-3. Tell the user what was written
-
-Use the absolute path for \`envPath\` \u2014 it's the Claude Code working directory + \`/.env\`.
-
-## Error handling
-- \`click_element\` not found \u2192 \`scroll_page("down")\` then retry
-- Still not found \u2192 \`take_screenshot()\` then \`highlight_region(x,y,w,h,msg)\`
-- Page still loading \u2192 \`take_screenshot()\` to confirm, proceed when content is visible
-- Never use Bash to work around a stuck browser interaction
-`;
-function isRunningViaNpx() {
-  return process.env.npm_execpath?.includes("npx") === true || process.argv[1]?.includes("_npx") === true || process.env.npm_config_user_agent?.includes("npm") === true;
-}
-function patchClaudeJson(serverScriptPath) {
-  let config = {};
-  if (existsSync(CLAUDE_JSON_PATH)) {
-    try {
-      config = JSON.parse(readFileSync(CLAUDE_JSON_PATH, "utf8"));
-    } catch {
-      config = {};
-    }
-  }
-  if (!config.mcpServers || typeof config.mcpServers !== "object") {
-    config.mcpServers = {};
-  }
-  const entry = isRunningViaNpx() ? { command: "npx", args: ["-y", "chromeflow"] } : { command: "node", args: [serverScriptPath] };
-  config.mcpServers.chromeflow = entry;
-  writeFileSync(CLAUDE_JSON_PATH, JSON.stringify(config, null, 2) + "\n");
-}
-function patchProjectClaudeMd(cwd, force = false) {
-  const claudeMdPath = join(cwd, "CLAUDE.md");
-  const content = getClaudeMdContent();
-  if (existsSync(claudeMdPath)) {
-    const existing = readFileSync(claudeMdPath, "utf8");
-    if (existing.includes("chromeflow")) {
-      if (!force) return "already-present";
-      const before = existing.slice(0, existing.indexOf("# Chromeflow")).trimEnd();
-      writeFileSync(claudeMdPath, (before ? before + "\n\n" : "") + content);
-      return "updated";
-    }
-    writeFileSync(claudeMdPath, existing.trimEnd() + "\n\n" + content);
-    return "appended";
-  }
-  writeFileSync(claudeMdPath, content);
-  return "created";
-}
-const CHROMEFLOW_TOOLS = [
-  "open_page",
-  "take_screenshot",
-  "clear_overlays",
-  "get_elements",
-  "execute_script",
-  "fill_input",
-  "read_element",
-  "get_page_text",
-  "write_to_env",
-  "scroll_page",
-  "click_element",
-  "wait_for_click",
-  "wait_for_selector",
-  "find_and_highlight",
-  "highlight_region",
-  // v0.1.23+
-  "switch_to_tab",
-  "list_tabs",
-  "get_form_fields",
-  "scroll_to_element",
-  "save_page_state",
-  "restore_page_state",
-  // v0.1.25+ → merged into take_screenshot in v0.7.0
-  // v0.1.32+
-  "fill_form",
-  // v0.1.36+
-  "set_file_input",
-  // v0.1.39+
-  "get_console_logs",
-  // v0.1.40+
-  "capture_terminal",
-  // v0.1.42+
-  "set_dialog_response",
-  // v0.1.46+
-  "type_text",
-  // v0.1.57+
-  "inspect_request_headers",
-  // v0.2.1+
-  "wait_for_change",
-  // v0.6.0+
-  "find_text",
-  "find_input",
-  "wait_for_text",
-  // v0.6.5+
-  "react_set_input",
-  // v0.8.0+
-  "react_call_prop"
-].map((t) => `mcp__chromeflow__${t}`);
-function patchSettingsLocalJson(cwd) {
-  const claudeDir = join(cwd, ".claude");
-  const settingsPath = join(claudeDir, "settings.local.json");
-  let settings = {};
-  if (existsSync(settingsPath)) {
-    try {
-      settings = JSON.parse(readFileSync(settingsPath, "utf8"));
-    } catch {
-      settings = {};
-    }
-  }
-  if (!settings.permissions || typeof settings.permissions !== "object") {
-    settings.permissions = {};
-  }
-  const perms = settings.permissions;
-  const existing = Array.isArray(perms.allow) ? perms.allow : [];
-  const withoutChromeflow = existing.filter((t) => !t.startsWith("mcp__chromeflow__"));
-  const merged = [...withoutChromeflow, ...CHROMEFLOW_TOOLS];
-  const changed = merged.length !== existing.length || CHROMEFLOW_TOOLS.some((t) => !existing.includes(t));
-  if (!changed) return "already-present";
-  perms.allow = merged;
-  if (!existsSync(claudeDir)) mkdirSync(claudeDir, { recursive: true });
-  writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n");
-  return "updated";
-}
-const STORE_URL = "https://chromewebstore.google.com/detail/chromeflow/lkdchdgkbkodliefobkkhiegjdiidime";
-function tryOpenStorePage() {
-  try {
-    execSync(`open "${STORE_URL}"`, { stdio: "ignore" });
-    return true;
-  } catch {
-    try {
-      execSync(`xdg-open "${STORE_URL}"`, { stdio: "ignore" });
-      return true;
-    } catch {
-      return false;
-    }
-  }
-}
-function patchGlobalClaudeMd() {
-  const globalClaudeMdPath = join(HOME, ".claude", "CLAUDE.md");
-  const hint = `## Chromeflow
-
-chromeflow is installed globally as an MCP server.
-
-If you are working in a project and the project's CLAUDE.md does not contain chromeflow
-instructions, tell the user: "Run \`npx chromeflow setup\` in this project directory to
-configure chromeflow for it."
-`;
-  if (existsSync(globalClaudeMdPath)) {
-    const existing = readFileSync(globalClaudeMdPath, "utf8");
-    if (existing.includes("chromeflow")) return "already-present";
-    writeFileSync(globalClaudeMdPath, existing.trimEnd() + "\n\n" + hint);
-    return "appended";
-  }
-  const dir = join(HOME, ".claude");
-  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
-  writeFileSync(globalClaudeMdPath, hint);
-  return "created";
-}
-async function runSetup() {
-  const scriptPath = fileURLToPath(import.meta.url);
-  const distDir = dirname(scriptPath);
-  const serverScriptPath = resolve(distDir, "index.js");
-  console.log("\nChromeflow Setup\n" + "\u2500".repeat(40));
-  patchClaudeJson(serverScriptPath);
-  const viaNpx = isRunningViaNpx();
-  console.log(`\u2713 Registered MCP server in ~/.claude.json`);
-  console.log(viaNpx ? `  \u2192 npx -y chromeflow (auto-updates)` : `  \u2192 node ${serverScriptPath}`);
-  const cwd = process.cwd();
-  const mdResult = patchProjectClaudeMd(cwd);
-  const settingsResult = patchSettingsLocalJson(cwd);
-  if (mdResult === "already-present") {
-    console.log("\u2713 CLAUDE.md already has chromeflow instructions (run `npx chromeflow update` to refresh)");
-  } else if (mdResult === "appended") {
-    console.log(`\u2713 Appended chromeflow instructions to ${join(cwd, "CLAUDE.md")}`);
-  } else {
-    console.log(`\u2713 Created ${join(cwd, "CLAUDE.md")}`);
-  }
-  if (settingsResult === "already-present") {
-    console.log("\u2713 .claude/settings.local.json already allows chromeflow tools");
-  } else {
-    console.log("\u2713 Added chromeflow tools to .claude/settings.local.json (no approval prompts)");
-  }
-  console.log("\nChrome extension (one-time step):");
-  const opened = tryOpenStorePage();
-  if (opened) {
-    console.log("  Opened Chrome Web Store \u2014 click 'Add to Chrome' to install.");
-  } else {
-    console.log(`  Install from the Chrome Web Store:
-  ${STORE_URL}`);
-  }
-  const globalResult = patchGlobalClaudeMd();
-  if (globalResult === "already-present") {
-    console.log("\u2713 ~/.claude/CLAUDE.md already has chromeflow hint");
-  } else if (globalResult === "appended") {
-    console.log("\u2713 Appended chromeflow hint to ~/.claude/CLAUDE.md");
-  } else {
-    console.log("\u2713 Created ~/.claude/CLAUDE.md with chromeflow hint");
-  }
-  console.log("\nDone. Restart Claude Code to activate chromeflow.\n");
-}
-async function runUninstall() {
-  const cwd = process.cwd();
-  console.log("\nChromeflow Uninstall\n" + "\u2500".repeat(40));
-  if (existsSync(CLAUDE_JSON_PATH)) {
-    try {
-      const config = JSON.parse(readFileSync(CLAUDE_JSON_PATH, "utf8"));
-      if (config.mcpServers && typeof config.mcpServers === "object") {
-        delete config.mcpServers.chromeflow;
-      }
-      writeFileSync(CLAUDE_JSON_PATH, JSON.stringify(config, null, 2) + "\n");
-      console.log("\u2713 Removed chromeflow MCP server from ~/.claude.json");
-    } catch {
-      console.log("  Could not update ~/.claude.json (skipping)");
-    }
-  }
-  const claudeMdPath = join(cwd, "CLAUDE.md");
-  if (existsSync(claudeMdPath)) {
-    const existing = readFileSync(claudeMdPath, "utf8");
-    if (existing.includes("# Chromeflow")) {
-      const idx = existing.indexOf("# Chromeflow");
-      const before = existing.slice(0, idx).trimEnd();
-      writeFileSync(claudeMdPath, before ? before + "\n" : "");
-      console.log(`\u2713 Removed chromeflow section from ${claudeMdPath}`);
-    }
-  }
-  const settingsPath = join(cwd, ".claude", "settings.local.json");
-  if (existsSync(settingsPath)) {
-    try {
-      const settings = JSON.parse(readFileSync(settingsPath, "utf8"));
-      const perms = settings.permissions;
-      if (perms && Array.isArray(perms.allow)) {
-        perms.allow = perms.allow.filter((t) => !t.startsWith("mcp__chromeflow__"));
-      }
-      writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n");
-      console.log("\u2713 Removed chromeflow tools from .claude/settings.local.json");
-    } catch {
-      console.log("  Could not update .claude/settings.local.json (skipping)");
-    }
-  }
-  const globalClaudeMdPath = join(HOME, ".claude", "CLAUDE.md");
-  if (existsSync(globalClaudeMdPath)) {
-    const existing = readFileSync(globalClaudeMdPath, "utf8");
-    if (existing.includes("## Chromeflow")) {
-      const idx = existing.indexOf("## Chromeflow");
-      const before = existing.slice(0, idx).trimEnd();
-      writeFileSync(globalClaudeMdPath, before ? before + "\n" : "");
-      console.log("\u2713 Removed chromeflow hint from ~/.claude/CLAUDE.md");
-    }
-  }
-  console.log("\nDone. Restart Claude Code to complete removal.\n");
-}
-async function fetchLatestClaudeMd() {
-  try {
-    const res = await fetch("https://unpkg.com/chromeflow@latest/CLAUDE.md");
-    if (res.ok) return await res.text();
-  } catch {
-  }
-  return getClaudeMdContent();
-}
-async function runUpdate() {
-  const cwd = process.cwd();
-  console.log("\nChromeflow Update\n" + "\u2500".repeat(40));
-  const freshContent = await fetchLatestClaudeMd();
-  const claudeMdPath = join(cwd, "CLAUDE.md");
-  let mdResult;
-  if (existsSync(claudeMdPath)) {
-    const existing = readFileSync(claudeMdPath, "utf8");
-    if (existing.includes("# Chromeflow")) {
-      const before = existing.slice(0, existing.indexOf("# Chromeflow")).trimEnd();
-      const newContent = (before ? before + "\n\n" : "") + freshContent;
-      if (newContent === existing) {
-        mdResult = "unchanged";
-      } else {
-        writeFileSync(claudeMdPath, newContent);
-        mdResult = "updated";
-      }
-    } else {
-      writeFileSync(claudeMdPath, existing.trimEnd() + "\n\n" + freshContent);
-      mdResult = "appended";
-    }
-  } else {
-    writeFileSync(claudeMdPath, freshContent);
-    mdResult = "created";
-  }
-  if (mdResult === "unchanged") {
-    console.log(`\u2713 ${claudeMdPath} already up to date`);
-  } else if (mdResult === "updated") {
-    console.log(`\u2713 Updated chromeflow instructions in ${claudeMdPath}`);
-  } else if (mdResult === "appended") {
-    console.log(`\u2713 Appended chromeflow instructions to ${claudeMdPath}`);
-  } else {
-    console.log(`\u2713 Created ${claudeMdPath}`);
-  }
-  const settingsResult = patchSettingsLocalJson(cwd);
-  if (settingsResult === "already-present") {
-    console.log("\u2713 .claude/settings.local.json already up to date");
-  } else {
-    console.log("\u2713 Updated chromeflow tools in .claude/settings.local.json");
-  }
-  console.log("Done.\n");
-}
-function readGlobalChromeflowVersion() {
-  try {
-    const root = execSync("npm root -g", { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
-    const pkgPath = join(root, "chromeflow", "package.json");
-    if (!existsSync(pkgPath)) return null;
-    return JSON.parse(readFileSync(pkgPath, "utf8")).version;
-  } catch {
-    return null;
-  }
-}
-function listNpxCachedChromeflowVersions() {
-  const cacheDir = join(HOME, ".npm", "_npx");
-  if (!existsSync(cacheDir)) return [];
-  const out = [];
-  let entries;
-  try {
-    entries = readdirSync(cacheDir);
-  } catch {
-    return [];
-  }
-  for (const hash of entries) {
-    const pkgPath = join(cacheDir, hash, "node_modules", "chromeflow", "package.json");
-    if (!existsSync(pkgPath)) continue;
-    try {
-      const v = JSON.parse(readFileSync(pkgPath, "utf8")).version;
-      out.push({ hash, version: v });
-    } catch {
-    }
-  }
-  return out;
-}
-async function fetchLatestPublishedVersion() {
-  try {
-    const res = await fetch("https://registry.npmjs.org/chromeflow/latest");
-    if (!res.ok) return null;
-    const json = await res.json();
-    return json.version ?? null;
-  } catch {
-    return null;
-  }
-}
-function compareSemver(a, b) {
-  const pa = a.split(".").map(Number);
-  const pb = b.split(".").map(Number);
-  for (let i = 0; i < 3; i++) {
-    const da = pa[i] ?? 0;
-    const db = pb[i] ?? 0;
-    if (da !== db) return da - db;
-  }
-  return 0;
-}
-async function runDoctor(runningVersion) {
-  console.log("\nChromeflow Doctor\n" + "\u2500".repeat(40));
-  const installScript = fileURLToPath(import.meta.url);
-  console.log(`Running version:  ${runningVersion}`);
-  console.log(`Running from:     ${installScript}`);
-  const globalVersion = readGlobalChromeflowVersion();
-  console.log(`Global install:   ${globalVersion ?? "(none \u2014 not installed via `npm install -g chromeflow`)"}`);
-  const npxCaches = listNpxCachedChromeflowVersions();
-  if (npxCaches.length === 0) {
-    console.log(`npx cache:        (empty)`);
-  } else {
-    console.log(`npx cache (${npxCaches.length} ${npxCaches.length === 1 ? "entry" : "entries"}):`);
-    for (const c of npxCaches) console.log(`  ${c.hash}: ${c.version}`);
-  }
-  const latest = await fetchLatestPublishedVersion();
-  console.log(`Latest on npm:    ${latest ?? "(unable to reach https://registry.npmjs.org)"}`);
-  const allKnown = [runningVersion];
-  if (globalVersion) allKnown.push(globalVersion);
-  for (const c of npxCaches) allKnown.push(c.version);
-  const stale = latest ? allKnown.some((v) => v !== "unknown" && compareSemver(v, latest) < 0) : false;
-  if (stale) {
-    console.log("\n\u26A0 Stale chromeflow install detected.");
-    console.log("  Reinstall recipe:");
-    console.log("    npm uninstall -g chromeflow");
-    console.log("    rm -rf ~/.npm/_npx");
-    console.log("    npm install -g chromeflow@latest");
-    console.log("  Then restart Claude Code so the MCP server picks up the new version.");
-  } else if (latest && compareSemver(runningVersion, latest) === 0) {
-    console.log("\n\u2713 chromeflow is up to date.");
-  } else if (!latest) {
-    console.log("\n? Could not check the registry; skipping freshness check.");
-  } else {
-    console.log("\n\u2713 Running version is current.");
-  }
-  console.log("\nTools shipped in this build (from setup manifest):");
-  const toolNames = CHROMEFLOW_TOOLS.map((t) => t.replace("mcp__chromeflow__", ""));
-  console.log("  " + toolNames.join(", "));
-  console.log(`  (${toolNames.length} tools)`);
-  console.log("\nIf chromeflow tools are missing in Claude Code:");
-  console.log("  1. Restart Claude Code (the MCP server is started at session start).");
-  console.log("  2. If still missing, run the reinstall recipe above.");
-  console.log("  3. Confirm the MCP startup log shows the version banner");
-  console.log(`     ([chromeflow] v${latest ?? "X.Y.Z"} \u2014 registered N tools).`);
-  console.log("");
-}
-export {
-  runDoctor,
-  runSetup,
-  runUninstall,
-  runUpdate
-};