@forhuman/flowmcp 0.1.0

package/lib/clients.sh

@@ -0,0 +1,107 @@
+#!/usr/bin/env bash
+# Resolves config file paths for supported MCP clients and merges the
+# mcpServers block into them without clobbering unrelated entries.
+
+wfw_os() {
+  case "$(uname -s)" in
+    Darwin) echo "macos" ;;
+    Linux) echo "linux" ;;
+    MINGW*|MSYS*|CYGWIN*) echo "windows" ;;
+    *) echo "unknown" ;;
+  esac
+}
+
+# wfw_client_config_path <client> <scope>
+# client: claude-code | claude-desktop | cursor
+# scope:  user | project   (project scope resolves relative to $PWD)
+wfw_client_config_path() {
+  local client="$1" scope="$2" os
+  os="$(wfw_os)"
+  case "$client" in
+    claude-code)
+      if [[ "$scope" == "project" ]]; then
+        echo "$PWD/.mcp.json"
+      else
+        echo "$HOME/.claude.json"
+      fi
+      ;;
+    claude-desktop)
+      if [[ "$scope" == "project" ]]; then
+        echo "error: claude-desktop has no project scope" >&2
+        return 1
+      fi
+      case "$os" in
+        macos) echo "$HOME/Library/Application Support/Claude/claude_desktop_config.json" ;;
+        linux) echo "$HOME/.config/Claude/claude_desktop_config.json" ;;
+        windows) echo "$APPDATA/Claude/claude_desktop_config.json" ;;
+        *) echo "error: unsupported OS for claude-desktop" >&2; return 1 ;;
+      esac
+      ;;
+    cursor)
+      if [[ "$scope" == "project" ]]; then
+        echo "$PWD/.cursor/mcp.json"
+      else
+        echo "$HOME/.cursor/mcp.json"
+      fi
+      ;;
+    *)
+      echo "error: unknown client '$client' (expected claude-code|claude-desktop|cursor)" >&2
+      return 1
+      ;;
+  esac
+}
+
+# wfw_client_merge_server <config_path> <server_name> <server_json> [--force]
+# Merges .mcpServers[server_name] = server_json into config_path, preserving
+# every other key in the file. Refuses to overwrite an existing entry unless
+# --force is passed. Creates parent dirs and a .bak backup of any existing file.
+wfw_client_merge_server() {
+  local config_path="$1" server_name="$2" server_json="$3" force="${4:-}"
+  local dir tmp existing
+  dir="$(dirname "$config_path")"
+  mkdir -p "$dir"
+
+  if [[ -f "$config_path" ]]; then
+    if ! jq empty "$config_path" >/dev/null 2>&1; then
+      echo "error: $config_path is not valid JSON — refusing to touch it" >&2
+      return 1
+    fi
+    existing="$(jq -r --arg n "$server_name" '.mcpServers[$n] // empty' "$config_path")"
+    if [[ -n "$existing" && "$force" != "--force" ]]; then
+      echo "error: '$server_name' already exists in $config_path (use --force to overwrite)" >&2
+      return 1
+    fi
+    cp "$config_path" "$config_path.bak"
+  else
+    echo '{}' > "$config_path"
+  fi
+
+  tmp="$(mktemp)"
+  jq --arg n "$server_name" --argjson s "$server_json" \
+    '.mcpServers = ((.mcpServers // {}) + {($n): $s})' \
+    "$config_path" > "$tmp" && mv "$tmp" "$config_path"
+}
+
+# wfw_build_server_json <org> <auth_method> — the mcpServers entry for an
+# org, shared by install.sh and rename.sh so both stay in sync.
+wfw_build_server_json() {
+  local org="$1" auth_method="$2"
+  if [[ "$auth_method" == "mcp-remote" ]]; then
+    local remote_dir
+    remote_dir="$(wfw_mcp_remote_dir "$org")"
+    jq -n --arg url "$WFW_MCP_URL" --arg dir "$remote_dir" \
+      '{command: "npx", args: ["-y", "mcp-remote", $url, "--resource", $url], env: {MCP_REMOTE_CONFIG_DIR: $dir}}'
+  else
+    local run_mcp_path="$WFW_COMMANDS_DIR/run-mcp.sh"
+    chmod +x "$run_mcp_path" 2>/dev/null || true
+    jq -n --arg cmd "$run_mcp_path" --arg org "$org" '{command: $cmd, args: [$org]}'
+  fi
+}
+
+wfw_client_remove_server() {
+  local config_path="$1" server_name="$2" tmp
+  [[ -f "$config_path" ]] || return 0
+  tmp="$(mktemp)"
+  jq --arg n "$server_name" 'if .mcpServers then .mcpServers |= del(.[$n]) else . end' \
+    "$config_path" > "$tmp" && mv "$tmp" "$config_path"
+}

package/lib/common.sh

@@ -0,0 +1,66 @@
+#!/usr/bin/env bash
+# Shared paths, env, and sanity checks for flowmcp.
+# Sourced by every command script. Never echo secrets from anything in lib/.
+
+set -euo pipefail
+
+WFW_HOME="${WFW_HOME:-$HOME/.flowmcp}"
+WFW_PROFILES_DIR="$WFW_HOME/profiles"
+WFW_SECRETS_DIR="$WFW_HOME/secrets"     # only used by the file-fallback backend
+WFW_AUDIT_DIR="$WFW_HOME/audit"
+WFW_MCP_REMOTE_BASE_DIR="$WFW_HOME/mcp-remote"   # per-org isolated mcp-remote token storage
+WFW_KEYCHAIN_SERVICE="flowmcp"
+WFW_MCP_URL="https://mcp.webflow.com/mcp"        # Webflow's official hosted MCP server
+
+wfw_ensure_dirs() {
+  umask 077
+  mkdir -p "$WFW_PROFILES_DIR" "$WFW_SECRETS_DIR" "$WFW_AUDIT_DIR" "$WFW_MCP_REMOTE_BASE_DIR"
+}
+
+# wfw_mcp_remote_dir <org> — isolated MCP_REMOTE_CONFIG_DIR so each org's
+# OAuth session against the same mcp.webflow.com URL never collides with
+# another org's.
+wfw_mcp_remote_dir() { echo "$WFW_MCP_REMOTE_BASE_DIR/$1"; }
+
+wfw_require_jq() {
+  command -v jq >/dev/null 2>&1 || {
+    echo "error: jq is required but not installed (https://jqlang.org)" >&2
+    exit 1
+  }
+}
+
+wfw_require_curl() {
+  command -v curl >/dev/null 2>&1 || {
+    echo "error: curl is required but not installed" >&2
+    exit 1
+  }
+}
+
+wfw_require_npx() {
+  command -v npx >/dev/null 2>&1 || {
+    echo "error: npx (Node.js) is required for the OAuth flow (connect) but not installed" >&2
+    exit 1
+  }
+}
+
+# wfw_json_mode <explicit-flag> — true if --json was passed OR stdout isn't
+# a real TTY (piped, captured by an agent's tool call, redirected to a file).
+# Lets every read command default to machine-readable output the moment a
+# human isn't directly watching the terminal, without requiring the caller
+# to know to pass --json.
+wfw_json_mode() {
+  [[ "$1" == "1" ]] && return 0
+  [[ ! -t 1 ]] && return 0
+  return 1
+}
+
+wfw_valid_org() {
+  [[ "$1" =~ ^[a-z0-9][a-z0-9_-]*$ ]]
+}
+
+wfw_profile_path() { echo "$WFW_PROFILES_DIR/$1.json"; }
+
+wfw_now() { date -u +"%Y-%m-%dT%H:%M:%SZ"; }
+
+wfw_ensure_dirs
+wfw_require_jq

package/lib/i18n.sh

@@ -0,0 +1,248 @@
+#!/usr/bin/env bash
+# Minimal i18n: detects/stores a human's language preference once, on their
+# first interactive run. Never touches JSON output — agents always get
+# English with fixed keys (see schema.sh). This only affects the
+# human-readable text a person actually reads (banner, --help, and the
+# plain-language guidance printed by add/connect/secret-set/rotate/list).
+
+WFW_LANG_FILE="$WFW_HOME/lang"
+
+# wfw_lang — resolves the active language: WFW_LANG env override, then the
+# saved preference file, then "en". Never prompts — safe to call anywhere,
+# including from a non-interactive/agent context.
+wfw_lang() {
+  if [[ -n "${WFW_LANG:-}" ]]; then
+    echo "$WFW_LANG"
+    return
+  fi
+  if [[ -f "$WFW_LANG_FILE" ]]; then
+    cat "$WFW_LANG_FILE"
+    return
+  fi
+  echo "en"
+}
+
+# wfw_prompt_lang_if_needed — asks once, only for a real interactive human
+# (both stdin and stdout are TTYs), with no saved preference and no WFW_LANG
+# override already set. Never runs for an agent's non-interactive Bash call
+# — same rule as secret-set/rotate: no command may block a non-interactive
+# run.
+wfw_prompt_lang_if_needed() {
+  [[ -n "${WFW_LANG:-}" ]] && return 0
+  [[ -f "$WFW_LANG_FILE" ]] && return 0
+  [[ -t 0 && -t 1 ]] || return 0
+
+  echo "Choose a language / Elige un idioma:"
+  echo "  [1] English"
+  echo "  [2] Español"
+  local choice
+  read -r -p "> " choice
+  case "$choice" in
+    2|es|Es|ES) echo "es" > "$WFW_LANG_FILE" ;;
+    *)          echo "en" > "$WFW_LANG_FILE" ;;
+  esac
+}
+
+# wfw_t <key> [args...] — looks up a human-facing message in the active
+# language and printf-substitutes any extra args into it (%s placeholders).
+# English is the fallback for any key not yet translated in Spanish, and for
+# any unknown key entirely (returns the key itself, so a typo is visible,
+# not silent).
+wfw_t() {
+  local key="$1"; shift || true
+  local msg
+  if [[ "$(wfw_lang)" == "es" ]]; then
+    msg="$(wfw_t_es "$key")"
+  else
+    msg="$(wfw_t_en "$key")"
+  fi
+  if [[ $# -gt 0 ]]; then
+    printf -- "$msg\n" "$@"
+  else
+    printf '%s\n' "$msg"
+  fi
+}
+
+wfw_t_es() {
+  local key="$1"
+  case "$key" in
+    tagline)              echo "conecta Webflow a tu agente de IA, sin exponer tus tokens" ;;
+    usage)                echo "USO" ;;
+    onboarding)           echo "PRIMEROS PASOS" ;;
+    daily_use)            echo "USO DIARIO" ;;
+    security_1)           echo "seguridad · esta herramienta nunca acepta un token como argumento y" ;;
+    security_2)           echo "nunca lo imprime. secret-set/rotate requieren una terminal interactiva real;" ;;
+    security_3)           echo "connect abre un navegador real (via mcp-remote, OAuth propio de Webflow — sin apps que configurar)." ;;
+    cmd_connect)          echo "<org> [--label NOMBRE] — agrega un cliente por navegador, sin configuración (recomendado)" ;;
+    cmd_add)              echo "<org> [--label NOMBRE] — registra solo los metadatos del org" ;;
+    cmd_secret_set)       echo "<org> — pega un token manualmente (alternativa sin navegador)" ;;
+    cmd_rotate)           echo "<org> — reemplaza un token guardado" ;;
+    cmd_list)             echo "lista los orgs registrados + último estado de test" ;;
+    cmd_inspect)          echo "<org> [--live] — muestra el detalle del perfil" ;;
+    cmd_test)             echo "<org> — valida las credenciales guardadas" ;;
+    cmd_install)          echo "<org> <client> [--scope user|project] [--force]" ;;
+    cmd_install_clients)  echo "client: claude-code | claude-desktop | cursor" ;;
+    cmd_remove)           echo "<org> --yes [--from client:scope]... — elimina perfil + credenciales" ;;
+    cmd_debug)            echo "<org> — diagnostica una conexión rota" ;;
+    cmd_rename)           echo "<old-org> <new-org> — sin necesidad de volver a autenticar" ;;
+    cmd_schema)           echo "referencia de comandos/JSON legible por máquina, para agentes" ;;
+    cmd_lang)             echo "[en|es] — ver o cambiar el idioma de la salida para humanos" ;;
+    msg_no_orgs)          echo "Todavía no hay orgs registrados. Corre 'flowmcp add <org>' para empezar." ;;
+    msg_reconnecting)     echo "reconectando org existente '%s'..." ;;
+    msg_connect_opening)  echo "Abriendo tu navegador para que '%s' apruebe el acceso a Webflow..." ;;
+    msg_connect_ctrlc1)   echo "En cuanto lo veas conectado abajo, presiona Ctrl+C para volver aquí — tu" ;;
+    msg_connect_ctrlc2)   echo "sesión ya queda guardada en disco en ese momento." ;;
+    msg_add_recommend)    echo "primero intenta 'flowmcp connect %s' — inicia sesión por navegador, sin copiar/pegar ningún token" ;;
+    msg_add_no_browser)   echo "¿Sin navegador disponible? Corre esto tú mismo, en tu propia terminal (no a través de un agente):" ;;
+    msg_add_run_yourself) echo "corre esto tú mismo, en tu propia terminal (no a través de un agente):" ;;
+    msg_add_explain1)     echo "Te va a pedir el token de la API de Webflow con entrada oculta y lo guardará" ;;
+    msg_add_explain2)     echo "directamente en %s. El token nunca se pasa como argumento de comando" ;;
+    msg_add_explain3)     echo "ni se imprime." ;;
+    msg_need_tty_secret)  echo "error: secret-set requiere una terminal interactiva (stdin no es una TTY)." ;;
+    msg_need_tty_rotate)  echo "error: rotate requiere una terminal interactiva (stdin no es una TTY)." ;;
+    msg_run_yourself1)    echo "Corre este comando tú mismo, en una ventana de terminal real — no le hagas" ;;
+    msg_run_yourself2)    echo "pipe de entrada ni lo corras vía un agente/herramienta de automatización." ;;
+    msg_run_yourself_short) echo "Corre este comando tú mismo, en una ventana de terminal real." ;;
+    msg_secretset_enter)  echo "Ingresa el token de la API de Webflow para '%s' (entrada oculta, presiona Enter al terminar):" ;;
+    msg_secretset_stored) echo "Token guardado para '%s' vía %s." ;;
+    msg_rotate_enter)     echo "Rotando el token de '%s'. Ingresa el nuevo token de la API de Webflow (entrada oculta):" ;;
+    msg_rotate_done)      echo "Token rotado para '%s' vía %s." ;;
+    msg_test_hint)        echo "Corre 'flowmcp test %s' para verificar que funciona." ;;
+    msg_test_hint_new)    echo "Corre 'flowmcp test %s' para verificar que el nuevo token funciona." ;;
+    msg_inspect_no_session) echo "nota: aún no hay sesión guardada para '%s' — corre 'flowmcp connect %s'" ;;
+    msg_inspect_no_token) echo "nota: aún no hay token guardado para '%s' — corre 'flowmcp secret-set %s'" ;;
+    msg_invalid_org)      echo "el nombre del org debe ser alfanumérico en minúsculas con - o _ (recibido '%s')" ;;
+    msg_org_not_found)    echo "no existe el org '%s'" ;;
+    msg_org_exists)       echo "el org '%s' ya existe (usa 'rotate' para cambiar su token, o 'remove' primero)" ;;
+    msg_add_ok)           echo "org '%s' registrado (label: %s) · backend de secretos: %s" ;;
+    msg_lang_set)         echo "idioma cambiado a %s" ;;
+    msg_connect_success)  echo "'%s' conectado vía OAuth de Webflow" ;;
+    msg_connect_next)     echo "flowmcp test %s — o 'install %s <client>' para conectarlo" ;;
+    msg_connect_fail)     echo "no se encontró una sesión completa para '%s' — puede que el login no haya terminado" ;;
+    msg_connect_fail_hint) echo "corre 'flowmcp connect %s' de nuevo y espera a que muestre conectado" ;;
+    msg_remove_confirm_needed) echo "esto elimina el perfil y el token guardado de '%s'." ;;
+    msg_remove_confirm_hint)   echo "vuelve a correrlo con --yes para confirmar" ;;
+    msg_remove_stripped)  echo "se quitó 'webflow-%s' de %s" ;;
+    msg_remove_ok)        echo "org '%s' eliminado (perfil + credenciales guardadas)" ;;
+    msg_install_no_org)   echo "no existe el org '%s' — corre 'flowmcp add %s' o 'connect %s' primero" ;;
+    msg_install_ok)       echo "'%s' instalado en %s" ;;
+    msg_install_note_mcpremote) echo "esta entrada corre mcp-remote contra el servidor MCP hosteado de Webflow — no hay ningún token en este archivo, mcp-remote lee su propia sesión aislada" ;;
+    msg_install_note_pat) echo "esta entrada hace referencia a run-mcp.sh, no a un token literal" ;;
+    msg_install_restart)  echo "reinicia %s para que lo tome" ;;
+    msg_rename_new_exists) echo "el org '%s' ya existe — elimínalo primero o elige otro nombre" ;;
+    msg_rename_ok)        echo "'%s' renombrado a '%s' — no hace falta volver a iniciar sesión" ;;
+    msg_rename_hint)      echo "reinicia cualquier cliente cuyo config se haya actualizado para que tome el nuevo nombre" ;;
+    msg_test_mcpremote_ok) echo "'%s' tiene una sesión de Webflow guardada (mcp-remote)" ;;
+    msg_test_note1)       echo "nota: esto solo confirma que hay una sesión guardada en tu computadora —" ;;
+    msg_test_note2)       echo "no la prueba contra Webflow todavía. Eso pasa solo, cuando abras Claude Code," ;;
+    msg_test_note3)       echo "Claude Desktop o Cursor: si venció, la renuevan o te piden iniciar sesión de nuevo." ;;
+    msg_test_pat_ok)      echo "el token de '%s' es válido · sitios accesibles: %s" ;;
+    msg_test_scopes)      echo "permisos: %s" ;;
+    msg_test_next_intro)  echo "instálalo en el cliente que uses:" ;;
+    dbg_header)           echo "== diagnóstico flowmcp: %s ==" ;;
+    dbg_done)             echo "== listo ==" ;;
+    dbg_sec_profile)      echo "perfil" ;;
+    dbg_sec_auth)         echo "método de auth: %s" ;;
+    dbg_sec_mcpremote_avail) echo "disponibilidad de mcp-remote" ;;
+    dbg_sec_secret_backend) echo "backend de secretos: %s" ;;
+    dbg_sec_wfmcp_avail)  echo "disponibilidad de webflow-mcp-server" ;;
+    dbg_sec_cred_check)   echo "verificación de credenciales" ;;
+    dbg_sec_client_configs) echo "configs de clientes conocidos" ;;
+    dbg_level_fail)       echo "FALLO" ;;
+    dbg_level_warn)       echo "AVISO" ;;
+    dbg_level_note)       echo "nota" ;;
+    *)                    wfw_t_en "$key" ;;
+  esac
+}
+
+wfw_t_en() {
+  local key="$1"
+  case "$key" in
+    tagline)              echo "connects Webflow to your AI agent, without exposing your tokens" ;;
+    usage)                echo "USAGE" ;;
+    onboarding)           echo "ONBOARDING" ;;
+    daily_use)            echo "DAILY USE" ;;
+    security_1)           echo "security · this tool never accepts a token as a command-line argument and" ;;
+    security_2)           echo "never prints one. secret-set/rotate require a real interactive TTY;" ;;
+    security_3)           echo "connect opens a real browser (via mcp-remote, Webflow's own OAuth — no app to set up)." ;;
+    cmd_connect)          echo "<org> [--label NAME] — add a client via browser, no setup needed (recommended)" ;;
+    cmd_add)              echo "<org> [--label NAME] — register org metadata only" ;;
+    cmd_secret_set)       echo "<org> — paste a token manually (headless fallback)" ;;
+    cmd_rotate)           echo "<org> — replace a stored token" ;;
+    cmd_list)             echo "list registered orgs + last test status" ;;
+    cmd_inspect)          echo "<org> [--live] — show profile detail" ;;
+    cmd_test)             echo "<org> — validate the stored credentials" ;;
+    cmd_install)          echo "<org> <client> [--scope user|project] [--force]" ;;
+    cmd_install_clients)  echo "client: claude-code | claude-desktop | cursor" ;;
+    cmd_remove)           echo "<org> --yes [--from client:scope]... — delete profile + credentials" ;;
+    cmd_debug)            echo "<org> — diagnose a broken connection" ;;
+    cmd_rename)           echo "<old-org> <new-org> — no re-login needed" ;;
+    cmd_schema)           echo "machine-readable command/JSON reference for agents" ;;
+    cmd_lang)             echo "[en|es] — view or change the human-readable output language" ;;
+    msg_no_orgs)          echo "No orgs registered yet. Run 'flowmcp add <org>' to start." ;;
+    msg_reconnecting)     echo "reconnecting existing org '%s'..." ;;
+    msg_connect_opening)  echo "Opening your browser for '%s' to approve access to Webflow..." ;;
+    msg_connect_ctrlc1)   echo "Once you see it connect below, press Ctrl+C to return here — your" ;;
+    msg_connect_ctrlc2)   echo "session is already saved to disk by that point." ;;
+    msg_add_recommend)    echo "try 'flowmcp connect %s' first — browser login, no token to copy/paste" ;;
+    msg_add_no_browser)   echo "No browser available? Run this yourself, in your own terminal (not through an agent):" ;;
+    msg_add_run_yourself) echo "run this yourself, in your own terminal (not through an agent):" ;;
+    msg_add_explain1)     echo "It will prompt for the Webflow API token with hidden input and store it" ;;
+    msg_add_explain2)     echo "directly in %s. The token is never passed as a command argument" ;;
+    msg_add_explain3)     echo "and never printed." ;;
+    msg_need_tty_secret)  echo "error: secret-set requires an interactive terminal (stdin is not a TTY)." ;;
+    msg_need_tty_rotate)  echo "error: rotate requires an interactive terminal (stdin is not a TTY)." ;;
+    msg_run_yourself1)    echo "Run this command yourself in a real terminal window — do not pipe input" ;;
+    msg_run_yourself2)    echo "into it and do not run it via an agent/automation tool." ;;
+    msg_run_yourself_short) echo "Run this command yourself in a real terminal window." ;;
+    msg_secretset_enter)  echo "Enter Webflow API token for '%s' (input hidden, press Enter when done):" ;;
+    msg_secretset_stored) echo "Stored token for '%s' via %s." ;;
+    msg_rotate_enter)     echo "Rotating token for '%s'. Enter the new Webflow API token (input hidden):" ;;
+    msg_rotate_done)      echo "Rotated token for '%s' via %s." ;;
+    msg_test_hint)        echo "Run 'flowmcp test %s' to verify it works." ;;
+    msg_test_hint_new)    echo "Run 'flowmcp test %s' to verify the new token works." ;;
+    msg_inspect_no_session) echo "note: no saved session yet for '%s' — run 'flowmcp connect %s'" ;;
+    msg_inspect_no_token) echo "note: no token stored yet for '%s' — run 'flowmcp secret-set %s'" ;;
+    msg_invalid_org)      echo "org name must be lowercase alphanumeric with - or _ (got '%s')" ;;
+    msg_org_not_found)    echo "no org '%s' registered" ;;
+    msg_org_exists)       echo "org '%s' already exists (use 'rotate' to change its token, or 'remove' first)" ;;
+    msg_add_ok)           echo "registered org '%s' (label: %s) · secret backend: %s" ;;
+    msg_lang_set)         echo "language set to %s" ;;
+    msg_connect_success)  echo "connected '%s' via Webflow's OAuth" ;;
+    msg_connect_next)     echo "flowmcp test %s — or 'install %s <client>' to wire it up" ;;
+    msg_connect_fail)     echo "no completed session found for '%s' — the login may not have finished" ;;
+    msg_connect_fail_hint) echo "run 'flowmcp connect %s' again and wait until it shows connected" ;;
+    msg_remove_confirm_needed) echo "this deletes the profile and the stored token for '%s'." ;;
+    msg_remove_confirm_hint)   echo "re-run with --yes to confirm" ;;
+    msg_remove_stripped)  echo "removed 'webflow-%s' from %s" ;;
+    msg_remove_ok)        echo "removed org '%s' (profile + stored credentials)" ;;
+    msg_install_no_org)   echo "no org '%s' registered — run 'flowmcp add %s' or 'connect %s' first" ;;
+    msg_install_ok)       echo "installed '%s' into %s" ;;
+    msg_install_note_mcpremote) echo "entry runs mcp-remote against Webflow's hosted MCP server — no token in this file, mcp-remote reads its own isolated session" ;;
+    msg_install_note_pat) echo "entry references run-mcp.sh, not a literal token" ;;
+    msg_install_restart)  echo "restart %s to pick it up" ;;
+    msg_rename_new_exists) echo "org '%s' already exists — remove it first or pick a different name" ;;
+    msg_rename_ok)        echo "renamed '%s' to '%s' — no re-login needed" ;;
+    msg_rename_hint)      echo "restart any client whose config was just updated to pick up the rename" ;;
+    msg_test_mcpremote_ok) echo "'%s' has a saved Webflow session (mcp-remote)" ;;
+    msg_test_note1)       echo "note: this only confirms a session file exists on your computer —" ;;
+    msg_test_note2)       echo "it doesn't check it against Webflow yet. That happens on its own when you" ;;
+    msg_test_note3)       echo "open Claude Code, Claude Desktop, or Cursor: expired sessions refresh or re-prompt automatically." ;;
+    msg_test_pat_ok)      echo "token for '%s' is valid · sites accessible: %s" ;;
+    msg_test_scopes)      echo "scopes: %s" ;;
+    msg_test_next_intro)  echo "install it into whichever client you're using:" ;;
+    dbg_header)           echo "== flowmcp debug: %s ==" ;;
+    dbg_done)             echo "== done ==" ;;
+    dbg_sec_profile)      echo "profile" ;;
+    dbg_sec_auth)         echo "auth method: %s" ;;
+    dbg_sec_mcpremote_avail) echo "mcp-remote availability" ;;
+    dbg_sec_secret_backend) echo "secret backend: %s" ;;
+    dbg_sec_wfmcp_avail)  echo "webflow-mcp-server availability" ;;
+    dbg_sec_cred_check)   echo "credential check" ;;
+    dbg_sec_client_configs) echo "known client configs" ;;
+    dbg_level_fail)       echo "FAIL" ;;
+    dbg_level_warn)       echo "WARN" ;;
+    dbg_level_note)       echo "note" ;;
+    *)                    echo "$key" ;;
+  esac
+}

package/lib/oauth.sh

@@ -0,0 +1,22 @@
+#!/usr/bin/env bash
+# OAuth for the mcp-remote path: Webflow hosts its own MCP server at
+# $WFW_MCP_URL with an OAuth server that supports Dynamic Client
+# Registration + PKCE (no client_secret, no manual app to create — verified
+# against the real endpoint). We don't implement the OAuth dance ourselves;
+# `npx mcp-remote` (github.com/punkpeye/mcp-remote) already does PKCE, DCR,
+# browser-opening, token storage, and refresh correctly. Our job is just to
+# give each org an isolated MCP_REMOTE_CONFIG_DIR so their sessions never
+# collide, and to check whether that directory holds a completed login.
+#
+# SECURITY NOTE: mcp-remote's on-disk token storage is outside our control
+# (it's a third-party tool). We don't read or touch the token files
+# ourselves — only check for their existence as a signal.
+
+# wfw_mcp_remote_connected <org> — true if a completed OAuth session
+# (access/refresh tokens, not just a half-finished PKCE attempt) exists.
+wfw_mcp_remote_connected() {
+  local dir
+  dir="$(wfw_mcp_remote_dir "$1")"
+  [[ -d "$dir" ]] || return 1
+  find "$dir" -type f -name '*_tokens.json' 2>/dev/null | grep -q .
+}

package/lib/profiles.sh

@@ -0,0 +1,58 @@
+#!/usr/bin/env bash
+# Non-sensitive profile metadata (org name, backend, last test result).
+# Never store token values here — see lib/secrets.sh.
+
+wfw_profile_exists() { [[ -f "$(wfw_profile_path "$1")" ]]; }
+
+wfw_profile_write_new() {
+  local org="$1" label="$2" auth_method="${3:-pat}" backend
+  backend="$(wfw_secret_backend)"
+  jq -n \
+    --arg org "$org" \
+    --arg label "$label" \
+    --arg created_at "$(wfw_now)" \
+    --arg backend "$backend" \
+    --arg auth_method "$auth_method" \
+    '{
+      org: $org,
+      label: $label,
+      created_at: $created_at,
+      secret_backend: $backend,
+      auth_method: $auth_method,
+      last_test: { timestamp: null, status: null, scopes: [], sites_count: null, error: null }
+    }' > "$(wfw_profile_path "$org")"
+}
+
+wfw_profile_set_auth_method() {
+  local org="$1" auth_method="$2" p tmp
+  p="$(wfw_profile_path "$org")"
+  tmp="$(mktemp)"
+  jq --arg m "$auth_method" '.auth_method = $m' "$p" > "$tmp" && mv "$tmp" "$p"
+}
+
+wfw_profile_read() { cat "$(wfw_profile_path "$1")"; }
+
+wfw_profile_update_last_test() {
+  local org="$1" status="$2" scopes_json="$3" sites_count="$4" error="$5"
+  local p tmp
+  p="$(wfw_profile_path "$org")"
+  tmp="$(mktemp)"
+  jq \
+    --arg ts "$(wfw_now)" \
+    --arg status "$status" \
+    --argjson scopes "$scopes_json" \
+    --argjson sites_count "$sites_count" \
+    --arg error "$error" \
+    '.last_test = { timestamp: $ts, status: $status, scopes: $scopes, sites_count: $sites_count, error: (if $error == "" then null else $error end) }' \
+    "$p" > "$tmp" && mv "$tmp" "$p"
+}
+
+wfw_profile_delete() { rm -f "$(wfw_profile_path "$1")"; }
+
+wfw_profile_list() {
+  shopt -s nullglob
+  for f in "$WFW_PROFILES_DIR"/*.json; do
+    basename "$f" .json
+  done
+  shopt -u nullglob
+}

package/lib/secrets.sh

@@ -0,0 +1,89 @@
+#!/usr/bin/env bash
+# Secret storage backend abstraction: OS keychain first, chmod-600 file fallback.
+#
+# SECURITY CONTRACT — read before touching this file:
+#   - secret_get MUST NEVER be called anywhere that prints its output to a
+#     terminal an agent can read back (no `echo "$(secret_get ...)"`,
+#     no command substitution that lands in a variable that later gets
+#     echoed/logged, no `set -x` in a scope that calls it).
+#   - The only two legitimate callers of secret_get are commands/test.sh
+#     and commands/run-mcp.sh, and both must consume the value directly
+#     into a curl header or an exported env var for a child process —
+#     never print it.
+#   - secret_set MUST NEVER accept the token as a CLI argument (visible in
+#     `ps`, shell history, and any agent tool-call transcript). It only
+#     reads from a variable already held in the calling shell (which itself
+#     must have come from an interactive `read -s`, never from an argv).
+
+wfw_secret_backend() {
+  if [[ "$(uname -s)" == "Darwin" ]] && command -v security >/dev/null 2>&1; then
+    echo "keychain-macos"
+  elif command -v secret-tool >/dev/null 2>&1; then
+    echo "keychain-linux"
+  else
+    echo "file"
+  fi
+}
+
+# secret_set <org> <token-var-name>
+# Pass the *name* of the variable holding the token, not the token itself,
+# so this function can unset it from the caller's scope when done.
+wfw_secret_set() {
+  local org="$1" varname="$2" backend
+  backend="$(wfw_secret_backend)"
+  local token="${!varname}"
+  case "$backend" in
+    keychain-macos)
+      security add-generic-password -a "$org" -s "$WFW_KEYCHAIN_SERVICE" -w "$token" -U >/dev/null
+      ;;
+    keychain-linux)
+      printf '%s' "$token" | secret-tool store --label="Webflow token ($org)" \
+        service "$WFW_KEYCHAIN_SERVICE" account "$org"
+      ;;
+    file)
+      local f="$WFW_SECRETS_DIR/$org.token"
+      umask 077
+      printf '%s' "$token" > "$f"
+      chmod 600 "$f"
+      ;;
+  esac
+  unset -v "$varname"
+}
+
+# secret_get <org> -> prints token to stdout. Callers must capture, not print.
+wfw_secret_get() {
+  local org="$1" backend
+  backend="$(wfw_secret_backend)"
+  case "$backend" in
+    keychain-macos)
+      security find-generic-password -a "$org" -s "$WFW_KEYCHAIN_SERVICE" -w 2>/dev/null
+      ;;
+    keychain-linux)
+      secret-tool lookup service "$WFW_KEYCHAIN_SERVICE" account "$org" 2>/dev/null
+      ;;
+    file)
+      cat "$WFW_SECRETS_DIR/$org.token" 2>/dev/null
+      ;;
+  esac
+}
+
+wfw_secret_exists() {
+  local org="$1"
+  [[ -n "$(wfw_secret_get "$org" || true)" ]]
+}
+
+wfw_secret_delete() {
+  local org="$1" backend
+  backend="$(wfw_secret_backend)"
+  case "$backend" in
+    keychain-macos)
+      security delete-generic-password -a "$org" -s "$WFW_KEYCHAIN_SERVICE" >/dev/null 2>&1 || true
+      ;;
+    keychain-linux)
+      secret-tool clear service "$WFW_KEYCHAIN_SERVICE" account "$org" >/dev/null 2>&1 || true
+      ;;
+    file)
+      rm -f "$WFW_SECRETS_DIR/$org.token"
+      ;;
+  esac
+}