@wickedevolutions/abilities-mcp 1.3.1 → 1.5.3

package/lib/cli/commands/upgrade-auth.js

@@ -0,0 +1,259 @@
+'use strict';
+
+const {
+  OAuthClient,
+  TokenManager,
+  AUTH_STATUS,
+  DEFAULT_SCOPE,
+} = require('../../auth');
+const { discover } = require('../../auth/discovery-client');
+const { makeRef, parseRef } = require('../../auth/secret-store');
+const { CliError, EXIT_USAGE, fromAuthError, withProgress } = require('../errors');
+const { subscribeProgress } = require('../output');
+const { readConfig, writeConfig } = require('../config-store');
+const testCmd = require('./test');
+
+/**
+ * `upgrade-auth <site_id> [--confirm]` — migrate an App Password site to
+ * OAuth without disturbing the App Password fallback.
+ *
+ * Implements the four-step sequence locked in Appendix F.5:
+ *
+ *   Step 1 — Pre-flight discovery. 404 → "Site does not have OAuth. Install
+ *            abilities-mcp-adapter v1.5.0+ first."
+ *   Step 2 — Dual-write: copy current apppassword credentials to
+ *            apppassword_fallback, then run the OAuth flow. On success the
+ *            site uses OAuth; the fallback remains.
+ *   Step 3 — Validation: run `test <site_id>`. On success, "✓ OAuth working.
+ *            App Password kept as fallback for now." On failure, revert.
+ *   Step 4 — `--confirm`: remove apppassword_fallback and delete the legacy
+ *            keychain entry.
+ *
+ * `upgrade-auth` without `--confirm` is idempotent (per F.5 prose) — running
+ * it twice on the same site is safe.
+ *
+ * Copyright (C) 2026 Influencentricity | Wicked Evolutions
+ * @license GPL-2.0-or-later
+ */
+
+const SECRET_SERVICE = 'abilities-mcp';
+
+async function run(args, ctx) {
+  const siteId = args._ && args._[0];
+  if (!siteId) {
+    throw new CliError('upgrade-auth requires a site_id argument', {
+      exitCode: EXIT_USAGE,
+      nextAction: 'Run: abilities-mcp upgrade-auth <site_id> [--confirm]',
+    });
+  }
+  const config = readConfig(ctx.configPath);
+  const site = config.sites[siteId];
+  if (!site) {
+    throw new CliError(`upgrade-auth: unknown site_id "${siteId}"`, {
+      exitCode: EXIT_USAGE,
+      nextAction: 'Run: abilities-mcp list-sites to see configured sites',
+    });
+  }
+
+  // ---- Step 4: --confirm cleans up the fallback. -----------------------
+  if (args.confirm) {
+    return _confirm(siteId, site, config, ctx);
+  }
+
+  if (site.auth.method === 'oauth' && !site.auth.apppassword_fallback) {
+    return {
+      exitCode: 0,
+      lines: [`Site "${siteId}" already uses OAuth with no App Password fallback.`,
+              `(Idempotent — nothing to do.)`],
+    };
+  }
+
+  if (site.auth.method !== 'apppassword') {
+    // OAuth-with-fallback case is allowed (Step 2 may have already run).
+    if (!(site.auth.method === 'oauth' && site.auth.apppassword_fallback)) {
+      throw new CliError(
+        `upgrade-auth: site "${siteId}" is not in a state we can upgrade (method=${site.auth.method})`,
+        {
+          exitCode: EXIT_USAGE,
+          nextAction: `Run: abilities-mcp list-sites and inspect the site state`,
+        }
+      );
+    }
+  }
+
+  const out = [];
+
+  // ---- Step 1: pre-flight discovery. -----------------------------------
+  out.push(`Step 1: pre-flight OAuth discovery for "${siteId}" (${site.url})…`);
+  const discoverFn = (ctx.deps && ctx.deps.discover) || discover;
+  try {
+    await discoverFn(site.url, {
+      pinned: !!site.oauth_capability_pinned,
+      pinnedFirstSeenAt: site.oauth_capability_pinned && site.oauth_capability_pinned.first_seen_at,
+      allowInsecure: ctx.allowInsecure,
+    });
+    out.push('  ✓ OAuth discovery succeeded.');
+  } catch (err) {
+    if (err && err.name === 'DiscoveryError') {
+      throw new CliError(
+        `Site ${siteId} does not have OAuth. Install abilities-mcp-adapter v1.5.0+ first.`,
+        {
+          exitCode: 4,
+          nextAction: 'Install / upgrade abilities-mcp-adapter on the site to v1.5.0 or later',
+          cause: err,
+        }
+      );
+    }
+    throw fromAuthError(err, { siteId });
+  }
+
+  // ---- Step 2: dual-write. ---------------------------------------------
+  out.push(`Step 2: running OAuth flow while keeping App Password as fallback…`);
+
+  // Stash the current apppassword credentials before the OAuth flow runs.
+  // If the operator has already done step 2 (resuming after a partial run),
+  // the fallback already exists and we leave it untouched.
+  let pendingFallback = site.auth.apppassword_fallback || null;
+  if (!pendingFallback && site.auth.method === 'apppassword') {
+    pendingFallback = {
+      username: site.auth.username,
+      password_ref: site.auth.password_ref,
+    };
+    // Move the keychain entry from <siteId>/apppassword to
+    // <siteId>/apppassword-legacy per the F.5 example. We do this before
+    // the OAuth flow so a mid-flow crash leaves us with a recoverable
+    // state (operator can re-run upgrade-auth).
+    const legacyAccount = `${siteId}/apppassword-legacy`;
+    try {
+      const oldAccount = parseRef(site.auth.password_ref).account;
+      const value = await ctx.secretStore.get(SECRET_SERVICE, oldAccount);
+      if (typeof value === 'string') {
+        await ctx.secretStore.set(SECRET_SERVICE, legacyAccount, value);
+      }
+    } catch {
+      // Non-fatal — operator may have already deleted the original entry.
+    }
+    pendingFallback = {
+      username: site.auth.username,
+      password_ref: makeRef(SECRET_SERVICE, legacyAccount),
+    };
+  }
+
+  const clientName = `${ctx.userLabel}'s Operator (${ctx.hostnameLabel})`;
+  const OAuthClientCls = (ctx.deps && ctx.deps.OAuthClient) || OAuthClient;
+  const oauth = new OAuthClientCls({
+    siteUrl: site.url,
+    clientName,
+    softwareVersion: ctx.softwareVersion,
+    scope: args.scope || DEFAULT_SCOPE,
+    identityProvider: ctx.identityProvider,
+    allowInsecure: ctx.allowInsecure,
+    capabilityPin: site.oauth_capability_pinned ? {
+      firstSeenAt: site.oauth_capability_pinned.first_seen_at,
+    } : null,
+    deps: ctx.deps && ctx.deps.oauthClientDeps,
+  });
+  subscribeProgress(oauth, out);
+
+  let result;
+  try { result = await oauth.run(); }
+  catch (err) {
+    out.push('✗ OAuth flow failed — config left unchanged. App Password remains primary.');
+    throw fromAuthError(err, { siteId });
+  }
+
+  const tm = new TokenManager({ secretStore: ctx.secretStore, allowInsecure: ctx.allowInsecure });
+  const persisted = await tm.persistTokens({ siteId, tokens: result.tokens });
+
+  site.auth = {
+    method: 'oauth',
+    client_id: result.clientId,
+    user_login: pendingFallback ? pendingFallback.username : (ctx.userLabel || 'operator'),
+    scopes: result.scopes,
+    access_token_expires_at: persisted.accessTokenExpiresAt,
+    refresh_token_expires_at: persisted.refreshTokenExpiresAt,
+    access_token_ref: persisted.accessTokenRef,
+    refresh_token_ref: persisted.refreshTokenRef,
+    apppassword_fallback: pendingFallback,
+  };
+  site.auth_status = AUTH_STATUS.ACTIVE;
+  site.oauth_capability_pinned = {
+    first_seen_at: result.capabilityPin.firstSeenAt,
+    last_confirmed_at: result.capabilityPin.lastConfirmedAt,
+  };
+  if (result.prMetadata && result.prMetadata.resource) {
+    site.mcp_resource = result.prMetadata.resource;
+  }
+  await writeConfig(ctx.configPath, config);
+
+  // ---- Step 3: validation via `test`. ----------------------------------
+  out.push(`Step 3: validating OAuth bearer with a ping…`);
+  let pingFailed = false;
+  let pingError;
+  try {
+    const testResult = await testCmd.run({ _: [siteId] }, ctx);
+    for (const line of testResult.lines) out.push(`  ${line}`);
+  } catch (err) {
+    pingFailed = true;
+    pingError = err;
+  }
+
+  if (pingFailed) {
+    // Spec wording (binding): "✗ OAuth test failed — reverting."
+    out.push('✗ OAuth test failed — reverting.');
+    if (pendingFallback) {
+      site.auth = {
+        method: 'apppassword',
+        username: pendingFallback.username,
+        password_ref: pendingFallback.password_ref,
+      };
+      site.auth_status = AUTH_STATUS.ACTIVE;
+      delete site.mcp_resource;
+      await writeConfig(ctx.configPath, config);
+    }
+    // Attach progress lines so the router prints "✗ OAuth test failed —
+    // reverting." on stdout alongside the stderr error from the ping.
+    throw withProgress(fromAuthError(pingError, { siteId }), out);
+  }
+
+  // Spec wording (binding):
+  //   "✓ OAuth working. App Password kept as fallback for now."
+  out.push('✓ OAuth working. App Password kept as fallback for now.');
+  out.push(`  Run: abilities-mcp upgrade-auth ${siteId} --confirm  (when ready to remove the fallback)`);
+  return { exitCode: 0, lines: out };
+}
+
+async function _confirm(siteId, site, config, ctx) {
+  if (site.auth.method !== 'oauth') {
+    throw new CliError(
+      `upgrade-auth --confirm: site "${siteId}" is not OAuth (method=${site.auth.method})`,
+      {
+        exitCode: EXIT_USAGE,
+        nextAction: `Run: abilities-mcp upgrade-auth ${siteId}  (without --confirm) first`,
+      }
+    );
+  }
+  if (!site.auth.apppassword_fallback) {
+    return {
+      exitCode: 0,
+      lines: [`Site "${siteId}" has no App Password fallback to remove. (Idempotent — nothing to do.)`],
+    };
+  }
+  // Delete the legacy keychain entry, then strip the fallback from config.
+  let legacyAccount;
+  try { legacyAccount = parseRef(site.auth.apppassword_fallback.password_ref).account; }
+  catch { legacyAccount = null; }
+  if (legacyAccount) {
+    await ctx.secretStore.delete(SECRET_SERVICE, legacyAccount).catch(() => {});
+  }
+  delete site.auth.apppassword_fallback;
+  await writeConfig(ctx.configPath, config);
+  return {
+    exitCode: 0,
+    // Spec wording (binding):
+    //   "✓ Migration complete. App Password removed. Site siteX now uses OAuth only."
+    lines: [`✓ Migration complete. App Password removed. Site ${siteId} now uses OAuth only.`],
+  };
+}
+
+module.exports = { run };

package/lib/cli/config-store.js

@@ -0,0 +1,328 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+
+const { SCHEMA_VERSION, validate, emptyConfig } = require('../auth/schema-v2');
+const { _atomicWrite } = require('../auth/config-migration');
+const { AUTH_STATUS } = require('../auth/events');
+const { makeRef } = require('../auth/secret-store');
+const { CliError, EXIT_CONFIG } = require('./errors');
+
+const SECRET_SERVICE = 'abilities-mcp';
+
+/**
+ * Read / write the v2 wp-sites.json file from a CLI command.
+ *
+ * This is the only place CLI commands touch the on-disk config — keeping it
+ * here means atomic-write, validation, and pathing rules live in one spot.
+ *
+ * Search order (matches lib/config.js so the MCP server and CLI agree on
+ * which file is "the" config):
+ *   1. --config=<path> explicit
+ *   2. <repo root>/wp-sites.json (alongside the bridge bin)
+ *   3. ~/.abilities-mcp/wp-sites.json
+ *
+ * If no file exists, `resolveConfigPath` returns the canonical home-dir path
+ * so commands like `add-site` write a fresh config there.
+ *
+ * Copyright (C) 2026 Influencentricity | Wicked Evolutions
+ * @license GPL-2.0-or-later
+ */
+
+const HOME_DIR_REL = path.join('.abilities-mcp', 'wp-sites.json');
+
+function _scriptRootConfig() {
+  // lib/cli/ → repo root
+  return path.resolve(__dirname, '..', '..', 'wp-sites.json');
+}
+
+function _homeConfig() {
+  return path.join(os.homedir(), HOME_DIR_REL);
+}
+
+/**
+ * Resolve the on-disk wp-sites.json path. Returns the first match in the
+ * search order, or the home-dir path if none exists yet.
+ *
+ * @param {object} [args]
+ * @param {string} [args.config]
+ * @returns {{ path: string, exists: boolean, source: 'explicit'|'script-root'|'home'|'home-default' }}
+ */
+function resolveConfigPath(args = {}) {
+  if (args.config) {
+    return {
+      path: path.resolve(args.config),
+      exists: fs.existsSync(args.config),
+      source: 'explicit',
+    };
+  }
+  const scriptCfg = _scriptRootConfig();
+  if (fs.existsSync(scriptCfg)) {
+    return { path: scriptCfg, exists: true, source: 'script-root' };
+  }
+  const homeCfg = _homeConfig();
+  if (fs.existsSync(homeCfg)) {
+    return { path: homeCfg, exists: true, source: 'home' };
+  }
+  return { path: homeCfg, exists: false, source: 'home-default' };
+}
+
+/**
+ * Read a v2 config file. Throws CliError on parse / validation failure.
+ *
+ * @param {string} filePath
+ * @returns {object}
+ */
+function readConfig(filePath) {
+  let raw;
+  try {
+    raw = fs.readFileSync(filePath, 'utf8');
+  } catch (err) {
+    if (err.code === 'ENOENT') {
+      throw new CliError(`Config not found: ${filePath}`, {
+        exitCode: EXIT_CONFIG,
+        nextAction: 'Run: abilities-mcp add-site <url> to create your first site',
+        cause: err,
+      });
+    }
+    throw new CliError(`Cannot read ${filePath}: ${err.message}`, {
+      exitCode: EXIT_CONFIG,
+      nextAction: 'Verify file permissions on the config path',
+      cause: err,
+    });
+  }
+  let parsed;
+  try { parsed = JSON.parse(raw); }
+  catch (err) {
+    throw new CliError(`Cannot parse ${filePath}: ${err.message}`, {
+      exitCode: EXIT_CONFIG,
+      nextAction: 'Inspect the JSON syntax of the config file',
+      cause: err,
+    });
+  }
+  if (parsed.schema_version !== SCHEMA_VERSION) {
+    throw new CliError(
+      `Config schema is v${parsed.schema_version || '<unknown>'} but CLI expects v${SCHEMA_VERSION}`,
+      {
+        exitCode: EXIT_CONFIG,
+        nextAction: 'Run the bridge once to trigger v1→v2 migration, or update the config manually',
+      }
+    );
+  }
+  const v = validate(parsed);
+  if (!v.ok) {
+    throw new CliError(
+      `Config failed v2 validation:\n  - ${v.errors.join('\n  - ')}`,
+      {
+        exitCode: EXIT_CONFIG,
+        nextAction: 'Fix the listed validation errors in the config file',
+      }
+    );
+  }
+  return parsed;
+}
+
+/**
+ * Atomically write a v2 config file. Validates before writing.
+ *
+ * @param {string} filePath
+ * @param {object} config
+ */
+async function writeConfig(filePath, config) {
+  const v = validate(config);
+  if (!v.ok) {
+    throw new CliError(
+      `Refusing to write invalid v2 config:\n  - ${v.errors.join('\n  - ')}`,
+      {
+        exitCode: EXIT_CONFIG,
+        nextAction: 'This is a CLI bug — please report it. The on-disk config was not modified.',
+      }
+    );
+  }
+  // Ensure parent dir exists (e.g. ~/.abilities-mcp/ on first add-site).
+  const dir = path.dirname(filePath);
+  await fs.promises.mkdir(dir, { recursive: true });
+  await _atomicWrite(filePath, config);
+}
+
+/**
+ * Build an empty v2 config skeleton. Used the first time `add-site` runs and
+ * no config exists yet.
+ * @returns {object}
+ */
+function freshConfig() {
+  return emptyConfig();
+}
+
+/**
+ * Derive a site-id from a URL hostname. Mirrors `add-site`'s deriveSiteId so a
+ * `.mcpb`-seeded site collides with a CLI-added entry for the same host (the
+ * file-absence guard in `seedFromEnvIfMissing` prevents the collision in
+ * practice; the parity matters for `upgrade-auth <site-id>` to be intuitive).
+ *
+ * @param {string} siteUrl
+ * @returns {string|null}  Site-id or null if URL is unparseable.
+ */
+function deriveSiteId(siteUrl) {
+  let host;
+  try { host = new URL(siteUrl).hostname; }
+  catch { return null; }
+  const trimmed = host.replace(/^www\./, '');
+  const dot = trimmed.indexOf('.');
+  return dot > 0 ? trimmed.slice(0, dot) : trimmed;
+}
+
+/**
+ * Seed wp-sites.json from env vars (`ABILITIES_MCP_URL/USERNAME/PASSWORD`)
+ * when the file doesn't yet exist. Used on first launch of the `.mcpb`
+ * extension 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.
+ *
+ * Behavior:
+ *  - If `configPath` already exists → no-op. Operators who manage their own
+ *    `wp-sites.json` are never overwritten.
+ *  - If keytar isn't loadable on this host (e.g. the .mcpb is somehow
+ *    running without the bundled keytar prebuild) → no-op. The bridge
+ *    falls back to env-var-only mode. Graceful degradation.
+ *  - If any of the three env vars is missing → no-op. Should not happen
+ *    in the .mcpb path (manifest user_config marks all three required) but
+ *    guards against partial env in other invocations.
+ *  - Otherwise: writes the App Password to keychain via the shared
+ *    SecretStore, builds a v2 apppassword entry shaped to pass both the
+ *    schema-v2 validator and the bridge's runtime validateSiteConfig
+ *    (matching the migration `_convertSite` pattern — preserves
+ *    `transport: 'http'` and the legacy http block alongside the v2 auth
+ *    block, with `password_ref` in both).
+ *
+ * If the keychain write succeeds but the file write fails the keychain
+ * entry is rolled back so the operator's keychain doesn't accumulate
+ * orphans on repeated failures.
+ *
+ * @param {string} configPath  Absolute path of the wp-sites.json to seed.
+ * @param {object} env         Environment shape — expects ABILITIES_MCP_URL,
+ *                             ABILITIES_MCP_USERNAME, ABILITIES_MCP_PASSWORD.
+ *                             Defaults to process.env.
+ * @param {object} [deps]
+ * @param {object} [deps.secretStore]  Inject for tests (a MemorySecretStore).
+ *                                     Defaults to a fresh KeychainSecretStore.
+ * @returns {Promise<{
+ *   seeded: boolean,
+ *   reason?: 'exists'|'missing-env-vars'|'keytar-unavailable'|'invalid-url'|'error',
+ *   siteId?: string,
+ *   configPath?: string,
+ *   error?: Error,
+ * }>}
+ */
+async function seedFromEnvIfMissing(configPath, env, deps = {}) {
+  if (!configPath) {
+    return { seeded: false, reason: 'missing-env-vars' };
+  }
+  if (fs.existsSync(configPath)) {
+    return { seeded: false, reason: 'exists' };
+  }
+
+  const url = env && env.ABILITIES_MCP_URL;
+  const username = env && env.ABILITIES_MCP_USERNAME;
+  const password = env && env.ABILITIES_MCP_PASSWORD;
+  if (!url || !username || !password) {
+    return { seeded: false, reason: 'missing-env-vars' };
+  }
+
+  let parsedUrl;
+  try { parsedUrl = new URL(url); }
+  catch { return { seeded: false, reason: 'invalid-url' }; }
+
+  const siteId = deriveSiteId(url);
+  if (!siteId) {
+    return { seeded: false, reason: 'invalid-url' };
+  }
+
+  // Lazily build a SecretStore so SSH-only / env-var-only setups never load
+  // keytar on the seed path — the no-op "missing env vars" exit above keeps
+  // them out, but keep the require deferred for symmetry with the runtime.
+  let secretStore = deps.secretStore;
+  if (!secretStore) {
+    const { KeychainSecretStore } = require('../auth/keychain-secret-store');
+    secretStore = new KeychainSecretStore();
+  }
+
+  // Probe keytar before writing. If it isn't loadable (e.g. the .mcpb
+  // somehow shipped without the bundled binary) we skip seeding — the
+  // bridge keeps working in env-var-only mode and the operator can run
+  // `abilities-mcp add-site` from a CLI install instead.
+  if (typeof secretStore.isAvailable === 'function') {
+    const available = await secretStore.isAvailable();
+    if (!available) {
+      return { seeded: false, reason: 'keytar-unavailable' };
+    }
+  }
+
+  // Build the endpoint the same way buildEnvConfig does — strip trailing
+  // slash, append the adapter route. This is the URL the runtime will hit
+  // for App-Password requests.
+  const base = (parsedUrl.origin + parsedUrl.pathname).replace(/\/+$/, '');
+  const endpoint = `${base}/wp-json/mcp/mcp-adapter-default-server`;
+  const account = `${siteId}/apppassword`;
+  const passwordRef = makeRef(SECRET_SERVICE, account);
+
+  // Write the secret to keychain first. If the file write below fails we
+  // roll this back so the keychain doesn't accumulate orphan entries on
+  // repeated seed attempts.
+  try {
+    await secretStore.set(SECRET_SERVICE, account, password);
+  } catch (err) {
+    return { seeded: false, reason: 'error', error: err };
+  }
+
+  const allowInsecure = parsedUrl.protocol === 'http:';
+  const site = {
+    label: parsedUrl.hostname,
+    url: parsedUrl.origin,
+    transport: 'http',
+    http: {
+      endpoint,
+      username,
+      password_ref: passwordRef,
+    },
+    auth: {
+      method: 'apppassword',
+      username,
+      password_ref: passwordRef,
+    },
+    auth_status: AUTH_STATUS.ACTIVE,
+  };
+  if (allowInsecure) site.allowInsecure = true;
+
+  const v2Config = {
+    $schema: 'https://wickedevolutions.com/schemas/abilities-mcp/wp-sites/v2.json',
+    schema_version: SCHEMA_VERSION,
+    defaultSite: siteId,
+    sites: { [siteId]: site },
+  };
+
+  try {
+    const dir = path.dirname(configPath);
+    await fs.promises.mkdir(dir, { recursive: true });
+    await _atomicWrite(configPath, v2Config);
+  } catch (err) {
+    // Roll back the keychain write so we don't leave an orphan secret.
+    try { await secretStore.delete(SECRET_SERVICE, account); }
+    catch { /* best-effort rollback */ }
+    return { seeded: false, reason: 'error', error: err };
+  }
+
+  return { seeded: true, siteId, configPath };
+}
+
+module.exports = {
+  resolveConfigPath,
+  readConfig,
+  writeConfig,
+  freshConfig,
+  seedFromEnvIfMissing,
+  deriveSiteId,
+  HOME_DIR_REL,
+};

package/lib/cli/context.js

@@ -0,0 +1,102 @@
+'use strict';
+
+const os = require('node:os');
+
+const {
+  KeychainSecretStore,
+  MemorySecretStore,
+  FreshEachTimeIdentityProvider,
+} = require('../auth');
+const { resolveConfigPath } = require('./config-store');
+
+/**
+ * CliContext — DI container the subcommands use to reach the outside world.
+ *
+ * The router builds one CliContext per invocation and hands it to the chosen
+ * command. Tests build their own context with `MemorySecretStore` and
+ * dependency-injected helpers (clock, fetch, identity provider) so they never
+ * touch real keychain or network.
+ *
+ * The context owns:
+ *   - secretStore           SecretStore instance (KeychainSecretStore by default)
+ *   - identityProvider      BridgeIdentityProvider (FreshEachTime in v1.0)
+ *   - configPath            absolute path to wp-sites.json
+ *   - debug                 boolean — when true, command errors include cause
+ *   - softwareVersion       bridge version (read from package.json)
+ *   - hostnameLabel         OS hostname, used in DCR client_name
+ *   - userLabel             username, used in DCR client_name
+ *   - now                   () => number (Date.now), test seam
+ *
+ * Copyright (C) 2026 Influencentricity | Wicked Evolutions
+ * @license GPL-2.0-or-later
+ */
+
+function _readPackageVersion() {
+  try {
+    // eslint-disable-next-line global-require
+    return require('../../package.json').version;
+  } catch {
+    return '0.0.0';
+  }
+}
+
+/**
+ * Build a real context for production CLI invocations.
+ *
+ * @param {object} args                Parsed CLI args (minimum: { config?, debug? })
+ * @returns {object} ctx
+ */
+function createContext(args = {}) {
+  const { path: configPath } = resolveConfigPath(args);
+  const secretStore = new KeychainSecretStore();
+  const identityProvider = new FreshEachTimeIdentityProvider({ store: secretStore });
+  return {
+    secretStore,
+    identityProvider,
+    configPath,
+    debug: !!args.debug,
+    allowInsecure: !!args.allowInsecure,
+    softwareVersion: _readPackageVersion(),
+    hostnameLabel: _safeHostname(),
+    userLabel: _safeUserLogin(),
+    now: () => Date.now(),
+  };
+}
+
+/**
+ * Build a test context. Uses MemorySecretStore unless caller overrides.
+ *
+ * @param {object} [overrides]
+ * @returns {object}
+ */
+function createTestContext(overrides = {}) {
+  const secretStore = overrides.secretStore || new MemorySecretStore();
+  const identityProvider = overrides.identityProvider
+    || new FreshEachTimeIdentityProvider({ store: secretStore });
+  return Object.assign({
+    secretStore,
+    identityProvider,
+    configPath: overrides.configPath || null,
+    debug: !!overrides.debug,
+    allowInsecure: overrides.allowInsecure !== false,   // tests default to true
+    softwareVersion: overrides.softwareVersion || '1.4.0-test',
+    hostnameLabel: overrides.hostnameLabel || 'host.local',
+    userLabel: overrides.userLabel || 'tester',
+    now: overrides.now || (() => Date.now()),
+  }, overrides);
+}
+
+function _safeHostname() {
+  try { return os.hostname(); } catch { return 'host.local'; }
+}
+
+function _safeUserLogin() {
+  try {
+    const u = os.userInfo();
+    return u.username || 'operator';
+  } catch {
+    return 'operator';
+  }
+}
+
+module.exports = { createContext, createTestContext };