@wickedevolutions/abilities-mcp 1.3.1 → 1.5.3

package/lib/config-source-line.js

@@ -0,0 +1,85 @@
+'use strict';
+
+const os = require('os');
+
+/**
+ * Format the operator-visible startup diagnostic line that names which config
+ * source `loadConfig` resolved to and what's in it.
+ *
+ * Output goes to stderr where Claude Desktop's MCP log captures it
+ * (visible in `mcp-server-WordPress (Abilities MCP).log` on macOS), so the
+ * operator can tell at a glance:
+ *  - Whether the .mcpb extension is in env-var single-site mode or has
+ *    handed off to a home-dir wp-sites.json.
+ *  - How many sites are configured and what auth method each uses.
+ *  - Which file path or env var is the source of truth right now.
+ *
+ * Discriminants set in `lib/config.js`:
+ *  - 'explicit-config' — args.config / --config=<path>
+ *  - 'script-adjacent' — wp-sites.json next to abilities-mcp.js
+ *  - 'home-dir'        — ~/.abilities-mcp/wp-sites.json
+ *  - 'env-var'         — ABILITIES_MCP_URL injected by Claude Desktop user_config
+ *  - 'legacy-cli'      — --host / --path (mcp-ssh-bridge backward compat)
+ *
+ * The line never includes secrets — only site IDs, auth methods, hostnames,
+ * tildified file paths, and counts.
+ *
+ * Copyright (C) 2026 Influencentricity | Wicked Evolutions
+ * @license GPL-2.0-or-later
+ */
+
+/**
+ * Replace a leading $HOME prefix with `~/` so logs don't leak the operator's
+ * full username path. No-op for paths outside $HOME.
+ */
+function tildify(p) {
+  if (!p) return p;
+  const home = os.homedir();
+  if (home && (p === home || p.startsWith(home + '/'))) {
+    return '~' + p.slice(home.length);
+  }
+  return p;
+}
+
+/**
+ * Per-site short auth label: prefer auth.method (v2 schema), fall back to
+ * transport (v1 schema), 'unknown' if neither is set.
+ */
+function siteAuthLabel(site) {
+  if (site && site.auth && site.auth.method) return site.auth.method;
+  if (site && site.transport) return site.transport;
+  return 'unknown';
+}
+
+/**
+ * Build the Config-source line.
+ *
+ * @param {object} config  Output of `loadConfig` — must carry `_configSource`
+ *                         and `_configSourceLabel`.
+ * @returns {string}       One-line operator diagnostic, no trailing newline.
+ */
+function formatConfigSourceLine(config) {
+  const source = config && config._configSource;
+  const rawLabel = (config && config._configSourceLabel) || '';
+
+  if (source === 'env-var') {
+    const site = config.sites && config.sites[config.defaultSite];
+    const username = (site && site.http && site.http.username) || '?';
+    return `Config source: ABILITIES_MCP_URL env var (single-site basic auth: ${rawLabel} as ${username})`;
+  }
+
+  if (source === 'legacy-cli') {
+    return `Config source: --host/--path legacy CLI (single-site SSH: ${rawLabel})`;
+  }
+
+  // File-based: explicit-config / script-adjacent / home-dir
+  const label = tildify(rawLabel);
+  const siteEntries = Object.entries(config.sites || {}).map(
+    ([id, site]) => `${id} ${siteAuthLabel(site)}`
+  );
+  const sitesHeader = siteEntries.length === 1 ? '1 site' : `${siteEntries.length} sites`;
+  const sourcePrefix = source ? `[${source}] ` : '';
+  return `Config source: ${sourcePrefix}${label} (${sitesHeader}: ${siteEntries.join(', ')})`;
+}
+
+module.exports = { formatConfigSourceLine, tildify, siteAuthLabel };

package/lib/config.js

@@ -1,40 +1,114 @@
 'use strict';
 
-const { execSync } = require('child_process');
+const { exec } = require('child_process');
+const { promisify } = require('util');
 const fs = require('fs');
+const fsp = require('fs').promises;
 const path = require('path');
 const os = require('os');
 
+const execAsync = promisify(exec);
+
 /**
- * Load configuration from wp-sites.json or build from CLI args.
+ * Load configuration from wp-sites.json, environment variables, or CLI args.
  *
- * Search order for wp-sites.json:
+ * Search order:
  *   1. --config=<path> explicit path
  *   2. Same directory as abilities-mcp.js
  *   3. ~/.abilities-mcp/wp-sites.json
+ *   4. ABILITIES_MCP_URL/USERNAME/PASSWORD env vars (single-site, .mcpb path)
+ *   5. --host/--path CLI args (legacy SSH single-site)
  *
- * If no config file and --host/--path provided, builds a single-site legacy config.
+ * Per Issue #5 / Phase E.2 (Stretch to Stable sprint): the startup chain
+ * — `resolveConfigFilePath`, `loadConfig`, `loadConfigFile`,
+ * `validateSiteConfig`, `resolvePassword` — is async so file reads and
+ * `passwordCommand` shell-outs do not block the event loop during boot.
  *
  * Copyright (C) 2026 Influencentricity | Wicked Evolutions
  * @license GPL-2.0-or-later
  */
-function loadConfig(args) {
+
+/**
+ * Async non-throwing existence check. Returns true iff the path resolves
+ * via fs.access(); any error (ENOENT, EACCES, …) yields false. Used by the
+ * search-order helpers which only care whether a candidate file is readable.
+ */
+async function _exists(p) {
+  try {
+    await fsp.access(p, fs.constants.F_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Resolve the on-disk wp-sites.json path that `loadConfig` would consume,
+ * without reading or validating it. Returns `null` when no file path applies
+ * (env-var single-site, legacy --host/--path, or no config at all).
+ *
+ * Used by the v1→v2 migration shim in `abilities-mcp.js` so the migration can
+ * run before `loadConfig` parses + validates a stale v1 file.
+ *
+ * Mirrors steps 1-3 of `loadConfig`'s search order. Steps 4-5 (env / legacy
+ * CLI) intentionally return `null` — there is no on-disk file to migrate.
+ *
+ * @param {object} args
+ * @returns {Promise<string|null>}  Absolute path of the resolved wp-sites.json, or null.
+ */
+async function resolveConfigFilePath(args) {
+  if (args && args.config) {
+    return path.resolve(args.config);
+  }
+  const scriptDir = path.resolve(__dirname, '..');
+  const scriptConfig = path.join(scriptDir, 'wp-sites.json');
+  if (await _exists(scriptConfig)) {
+    return scriptConfig;
+  }
+  const homeConfig = path.join(os.homedir(), '.abilities-mcp', 'wp-sites.json');
+  if (await _exists(homeConfig)) {
+    return homeConfig;
+  }
+  return null;
+}
+
+async function loadConfig(args) {
   // Explicit config path
   if (args.config) {
-    return loadConfigFile(args.config);
+    return loadConfigFile(args.config, 'explicit-config');
   }
 
   // Check alongside script (lib/ → package root)
   const scriptDir = path.resolve(__dirname, '..');
   const scriptConfig = path.join(scriptDir, 'wp-sites.json');
-  if (fs.existsSync(scriptConfig)) {
-    return loadConfigFile(scriptConfig);
+  if (await _exists(scriptConfig)) {
+    return loadConfigFile(scriptConfig, 'script-adjacent');
   }
 
   // Check home directory
   const homeConfig = path.join(os.homedir(), '.abilities-mcp', 'wp-sites.json');
-  if (fs.existsSync(homeConfig)) {
-    return loadConfigFile(homeConfig);
+  if (await _exists(homeConfig)) {
+    return loadConfigFile(homeConfig, 'home-dir');
+  }
+
+  // Env-var single-site config — covers the .mcpb install path and any
+  // env-var-based MCP client configuration (claude mcp add, Docker, etc.)
+  //
+  // First-launch seed (#34): if the .mcpb just installed and no home-dir
+  // wp-sites.json exists yet, seed one from the env vars so subsequent CLI
+  // commands (`list-sites`, `upgrade-auth`, `add-site`) operate on a single
+  // source of truth that already includes the site Claude Desktop is
+  // connected to. On success the bridge loads the freshly seeded file —
+  // same shape it would read on next restart — so the runtime path stays
+  // identical regardless of whether seeding just happened. On failure
+  // (keytar unavailable, file-already-exists, write error) the seed is a
+  // graceful no-op and we fall back to env-var-only mode below.
+  if (process.env.ABILITIES_MCP_URL) {
+    const seedResult = await _seedFromEnvIfMissing(homeConfig, process.env);
+    if (seedResult && seedResult.seeded) {
+      return loadConfigFile(homeConfig, 'home-dir');
+    }
+    return buildEnvConfig(process.env);
   }
 
   // Legacy CLI mode — single site from --host/--path
@@ -43,17 +117,90 @@ function loadConfig(args) {
   }
 
   throw new Error(
-    'No wp-sites.json found and no --host/--path provided.\n' +
-    'Create wp-sites.json or use: --host=<ssh-host> --path=<wp-path>'
+    'No configuration found.\n' +
+    'Provide one of: wp-sites.json, ABILITIES_MCP_URL+USERNAME+PASSWORD env vars, or --host/--path.'
   );
 }
 
-function loadConfigFile(filePath) {
-  const raw = fs.readFileSync(filePath, 'utf8');
+/**
+ * Build single-site config from env vars (ABILITIES_MCP_URL/USERNAME/PASSWORD).
+ *
+ * Auto-derives the MCP adapter endpoint from the site URL:
+ *   https://example.com  →  https://example.com/wp-json/mcp/mcp-adapter-default-server
+ *
+ * This is the path used by .mcpb bundles installed in Claude Desktop and any
+ * other env-var-based MCP client configuration.
+ */
+function buildEnvConfig(env) {
+  const rawUrl = env.ABILITIES_MCP_URL;
+  const username = env.ABILITIES_MCP_USERNAME;
+  const password = env.ABILITIES_MCP_PASSWORD;
+
+  if (!username) {
+    throw new Error('ABILITIES_MCP_URL is set but ABILITIES_MCP_USERNAME is missing');
+  }
+  if (!password) {
+    throw new Error('ABILITIES_MCP_URL is set but ABILITIES_MCP_PASSWORD is missing');
+  }
+
+  let parsedUrl;
+  try {
+    parsedUrl = new URL(rawUrl);
+  } catch (e) {
+    throw new Error(`ABILITIES_MCP_URL is not a valid URL: ${rawUrl}`);
+  }
+
+  const isHttps = parsedUrl.protocol === 'https:';
+  const isHttp = parsedUrl.protocol === 'http:';
+  if (!isHttps && !isHttp) {
+    throw new Error(`ABILITIES_MCP_URL must be http or https: ${rawUrl}`);
+  }
+
+  // Strip trailing slash from origin+path, then append the adapter route.
+  const base = (parsedUrl.origin + parsedUrl.pathname).replace(/\/+$/, '');
+  const endpoint = `${base}/wp-json/mcp/mcp-adapter-default-server`;
+
+  const siteConfig = {
+    label: parsedUrl.hostname,
+    url: parsedUrl.origin,
+    transport: 'http',
+    http: {
+      endpoint,
+      username,
+      password,
+    },
+  };
+
+  // Allow plain HTTP only when the operator explicitly opts in. The .mcpb path
+  // expects HTTPS by default; localhost dev gets a narrow exception.
+  if (isHttp) {
+    const isLocal = parsedUrl.hostname === 'localhost' || parsedUrl.hostname === '127.0.0.1';
+    if (!isLocal && env.ABILITIES_MCP_ALLOW_INSECURE !== 'true') {
+      throw new Error(
+        `ABILITIES_MCP_URL is HTTP (not HTTPS): ${rawUrl}\n` +
+        `Set ABILITIES_MCP_ALLOW_INSECURE=true to allow plain HTTP.`
+      );
+    }
+    siteConfig.allowInsecure = true;
+  }
+
+  return {
+    defaultSite: 'default',
+    _isMultiSite: false,
+    _configSource: 'env-var',
+    _configSourceLabel: parsedUrl.hostname,
+    sites: {
+      default: siteConfig,
+    },
+  };
+}
+
+async function loadConfigFile(filePath, source = 'explicit-config') {
+  const raw = await fsp.readFile(filePath, 'utf8');
 
   // Warn if config file is readable by group or world
   try {
-    const stat = fs.statSync(filePath);
+    const stat = await fsp.stat(filePath);
     if (stat.mode & 0o077) {
       process.stderr.write(
         `WARNING: ${filePath} is readable by group/world (mode ${(stat.mode & 0o777).toString(8)}). ` +
@@ -78,17 +225,69 @@ function loadConfigFile(filePath) {
 
   // Validate each site
   for (const [key, site] of Object.entries(config.sites)) {
-    validateSiteConfig(key, site);
+    await validateSiteConfig(key, site);
   }
 
   config._isMultiSite = Object.keys(config.sites).length > 1 ||
     Object.values(config.sites).some(s => s.multisite);
   config._configPath = filePath;
+  config._configSource = source;
+  config._configSourceLabel = filePath;
 
   return config;
 }
 
-function validateSiteConfig(key, site) {
+async function validateSiteConfig(key, site) {
+  // v2 OAuth sites carry no transport block (Appendix F.5 + add-site flow).
+  // The runtime treats them as HTTP — endpoint comes from auth.mcp_resource
+  // or site.mcp_resource (resolved by the OAuth-aware transport).
+  if (site.auth && site.auth.method === 'oauth') {
+    if (!site.url) {
+      throw new Error(`Site "${key}" (oauth): requires "url"`);
+    }
+    if (!site.auth.access_token_ref || !site.auth.refresh_token_ref) {
+      throw new Error(`Site "${key}" (oauth): requires auth.access_token_ref and auth.refresh_token_ref`);
+    }
+    if (!site.mcp_resource) {
+      throw new Error(`Site "${key}" (oauth): requires mcp_resource (set during add-site / reauth)`);
+    }
+    if (!site.mcp_resource.startsWith('https://') && !site.allowInsecure) {
+      throw new Error(`Site "${key}" (oauth): mcp_resource is not HTTPS. Set "allowInsecure": true on the site to allow HTTP`);
+    }
+    return;
+  }
+
+  // v2 App-Password sites — produced by config-migration from v1 transport-style
+  // configs. Secret lives in keychain (auth.password_ref); the legacy http.password*
+  // fields are stripped during migration so the keychain is the sole source of
+  // truth. Carrier transport (http or ssh) is preserved for the runtime.
+  if (site.auth && site.auth.method === 'apppassword') {
+    if (!site.auth.username) {
+      throw new Error(`Site "${key}" (apppassword): requires auth.username`);
+    }
+    if (!site.auth.password_ref) {
+      throw new Error(`Site "${key}" (apppassword): requires auth.password_ref`);
+    }
+    if (!site.transport) {
+      throw new Error(`Site "${key}" (apppassword): missing "transport" (ssh or http)`);
+    }
+    if (site.transport === 'ssh') {
+      if (!site.ssh || !site.ssh.host || !site.ssh.path) {
+        throw new Error(`Site "${key}" (apppassword/ssh): requires ssh.host and ssh.path`);
+      }
+    } else if (site.transport === 'http') {
+      if (!site.http || !site.http.endpoint) {
+        throw new Error(`Site "${key}" (apppassword/http): requires http.endpoint`);
+      }
+      if (!site.http.endpoint.startsWith('https://') && !site.allowInsecure) {
+        throw new Error(`Site "${key}" (apppassword/http): endpoint is not HTTPS. Set "allowInsecure": true on the site to allow HTTP`);
+      }
+    } else {
+      throw new Error(`Site "${key}" (apppassword): unknown transport "${site.transport}" (use ssh or http)`);
+    }
+    return;
+  }
+
   if (!site.transport) {
     throw new Error(`Site "${key}": missing "transport" (ssh or http)`);
   }
@@ -119,6 +318,8 @@ function buildLegacyConfig(args) {
   return {
     defaultSite: 'default',
     _isMultiSite: false,
+    _configSource: 'legacy-cli',
+    _configSourceLabel: args.host,
     sites: {
       default: {
         label: args.host,
@@ -137,6 +338,7 @@ function buildLegacyConfig(args) {
 
 /**
  * Resolve a composite site key like "wicked.community" into config + subsite URL.
+ * Pure in-memory dispatch — kept synchronous since it has no I/O.
  */
 function resolveSiteKey(config, compositeKey) {
   // Direct match — "helena" or "wicked"
@@ -189,17 +391,23 @@ function buildSiteKeyEnum(config) {
 }
 
 /**
- * Resolve the password for an HTTP transport config, supporting
- * plaintext password, environment variable, or shell command.
+ * Resolve the password for an HTTP transport config, supporting plaintext
+ * password, environment variable, or shell command.
+ *
+ * `passwordCommand` is dispatched through `util.promisify(exec)` so the shell
+ * interprets the command string the same way the previous `execSync` did
+ * (operators rely on pipes, redirects, and command chaining — e.g.
+ * `op read 'op://Vault/foo' | tr -d '\n'` — which `execFile` cannot run).
  */
-function resolvePassword(httpConfig) {
+async function resolvePassword(httpConfig) {
   if (httpConfig.passwordEnv) {
     const val = process.env[httpConfig.passwordEnv];
     if (!val) throw new Error(`Environment variable ${httpConfig.passwordEnv} is not set`);
     return val;
   }
   if (httpConfig.passwordCommand) {
-    return execSync(httpConfig.passwordCommand, { encoding: 'utf8' }).trim();
+    const { stdout } = await execAsync(httpConfig.passwordCommand, { encoding: 'utf8' });
+    return stdout.trim();
   }
   if (httpConfig.password) {
     return httpConfig.password;
@@ -207,4 +415,56 @@ function resolvePassword(httpConfig) {
   throw new Error('No password, passwordEnv, or passwordCommand configured');
 }
 
-module.exports = { loadConfig, resolvePassword, resolveSiteKey, buildSiteKeyEnum };
+/**
+ * Resolve a site's HTTP password, dispatching on schema shape.
+ *
+ * v2 App-Password sites (auth.method === 'apppassword' + auth.password_ref)
+ * read the secret from the keychain via the SecretStore. v1 carriers without
+ * a ref fall back to the `resolvePassword(http)` resolver.
+ *
+ * @param {object} site
+ * @param {object} [secretStore]  SecretStore instance. Lazily defaults to
+ *                                KeychainSecretStore when an apppassword path
+ *                                runs and no store was supplied — preserves
+ *                                the "no keytar for SSH-only / v1-only setups"
+ *                                property by deferring the require to the
+ *                                point of need.
+ * @returns {Promise<string>}
+ */
+async function resolveSitePassword(site, secretStore) {
+  if (site && site.auth && site.auth.method === 'apppassword' && site.auth.password_ref) {
+    let store = secretStore;
+    if (!store) {
+      const { KeychainSecretStore } = require('./auth/keychain-secret-store');
+      store = new KeychainSecretStore();
+    }
+    const { resolveRef } = require('./auth/secret-store');
+    return resolveRef(store, site.auth.password_ref);
+  }
+  if (site && site.http) {
+    return resolvePassword(site.http);
+  }
+  throw new Error('No password source configured for site');
+}
+
+/**
+ * Lazy wrapper around `lib/cli/config-store.js#seedFromEnvIfMissing`. Only
+ * loads the CLI config-store + KeychainSecretStore modules when the env-var
+ * branch of `loadConfig` actually fires — so SSH-only, explicit-config, and
+ * legacy-CLI install paths never pay the keytar import cost.
+ */
+async function _seedFromEnvIfMissing(configPath, env) {
+  const { seedFromEnvIfMissing } = require('./cli/config-store');
+  return seedFromEnvIfMissing(configPath, env);
+}
+
+module.exports = {
+  loadConfig,
+  resolveConfigFilePath,
+  resolvePassword,
+  resolveSitePassword,
+  resolveSiteKey,
+  buildSiteKeyEnum,
+  buildEnvConfig,
+  validateSiteConfig,
+};