@chenguangyao/devflow-kit 0.1.43

package/src/cli/commands/provider.js

@@ -0,0 +1,698 @@
+'use strict';
+const fs = require('fs/promises');
+const fsSync = require('fs');
+const readline = require('readline');
+const log = require('../../utils/log.js');
+const paths = require('../../core/paths.js');
+const providers = require('../../providers/loader.js');
+const lifecycle = require('../../providers/lifecycle.js');
+const userconfig = require('../../providers/userconfig.js');
+const projects = require('../../core/projects.js');
+
+/**
+ * Resolve the providers.json file path for a given scope.
+ *
+ *   --scope=user    (default)  → ~/.devflow/providers.json
+ *   --scope=project            → <repo>/devflow/providers.json
+ *
+ * "user" is default because that's the recommended single source of truth across
+ * all projects; project-level is reserved for repo-specific overrides (e.g. a
+ * project that needs its own kb endpoint different from the team default).
+ */
+function scopeFile(root, flags) {
+  const scope = flags.scope || 'user';
+  if (scope === 'project') return { scope, file: paths.projectProvidersFile(root) };
+  if (scope === 'user' || scope === 'global') return { scope: 'user', file: paths.userProvidersFile() };
+  throw new Error(`unknown --scope: ${scope} (expected: user | project)`);
+}
+
+async function run({ sub, flags = {}, positional = [], cwd }) {
+  const root = cwd || process.cwd();
+  const action = sub || positional[0];
+  switch (action) {
+    case 'list':    return list(root);
+    case 'status':  return status(root, positional[0] || flags.name);
+    case 'add':     return add(root, positional[0] || flags.name, flags);
+    case 'setup':   return setup(root, flags);
+    case 'import':  return importConfig(root, positional[0] || flags.format, flags);
+    case 'remove':  return remove(root, positional[0] || flags.name, flags);
+    case 'relogin': return relogin(root, positional[0] || flags.name, flags);
+    case 'rotate':  return rotate(root, positional[0] || flags.name, flags);
+    case 'logout':  return logout(root, positional[0] || flags.name);
+    case 'audit':   return audit(root);
+    case undefined:
+    case 'help':    return help();
+    default:
+      log.error(`unknown subcommand: ${action}`);
+      help();
+      process.exitCode = 2;
+  }
+}
+
+async function importConfig(_root, format, flags) {
+  if (!format || !flags.from) {
+    log.error('usage: devflow provider import publish-code --from=<file.json>');
+    process.exitCode = 2;
+    return;
+  }
+  if (format !== 'publish-code') {
+    log.error(`unknown import format: ${format}`);
+    process.exitCode = 2;
+    return;
+  }
+  const result = await projects.importPublishCodeConfig(require('path').resolve(_root, flags.from));
+  log.ok(`imported ${result.imported} project(s) into ${result.file}`);
+  if (result.skipped) log.warn(`skipped ${result.skipped} malformed project(s)`);
+  log.dim('credentials were not imported; use env vars or devflow provider rotate for Jenkins/GitLab secrets.');
+}
+
+async function list(root) {
+  const arr = await providers.listConfigured(root);
+  if (!arr.length) {
+    log.info('no providers configured. defaults: local for every type.');
+    return;
+  }
+  for (const p of arr) log.raw(`  ${p.name.padEnd(28)} ${p.type.padEnd(8)} ${p.driver.padEnd(14)} [${p.source}]`);
+}
+
+async function status(root, name) {
+  if (!name) {
+    const arr = await providers.listConfigured(root);
+    if (!arr.length) { log.info('no providers configured.'); return; }
+    let bad = 0;
+    for (const p of arr) {
+      const s = await statusOne(root, p.name);
+      if (!s.ok) bad++;
+    }
+    if (bad > 0) process.exitCode = 1;
+    return;
+  }
+  const s = await statusOne(root, name);
+  if (!s.ok) process.exitCode = 1;
+}
+
+async function statusOne(root, name) {
+  let p;
+  try { p = await providers.load(root, { name }); }
+  catch (e) {
+    log.warn(`${name.padEnd(28)} load-error: ${e.message.split('\n')[0]}`);
+    return { ok: false };
+  }
+  let v;
+  try { v = await p.validate(); }
+  catch (e) { log.warn(`${name.padEnd(28)} validate-error: ${e.message}`); return { ok: false }; }
+  if (v.ok) {
+    log.ok(`${name.padEnd(28)} ok`);
+    return { ok: true };
+  }
+  const flag = v.needsLogin ? '!login' : '!error';
+  log.warn(`${name.padEnd(28)} ${flag.padEnd(8)} ${v.reason || 'unknown'}`);
+  return { ok: false };
+}
+
+async function add(root, name, flags) {
+  if (!name) {
+    log.error('usage: devflow provider add <name> [--scope=user|project] [--type=<t>] [--driver=<d>] [--config-key=value ...] [--from=<file.json>]');
+    process.exitCode = 2;
+    return;
+  }
+  // Default scope is "user" (~/.devflow/providers.json) so all credentials
+  // live in one place. `--scope=project` writes to <repo>/devflow/providers.json
+  // for repo-specific overrides.
+  const { scope, file } = scopeFile(root, flags);
+  if (scope === 'user') await userconfig.ensureUserConfig();
+  let cur = {};
+  if (fsSync.existsSync(file)) cur = JSON.parse(await fs.readFile(file, 'utf8'));
+  const existing = cur[name] || { type: '', driver: '', config: {} };
+
+  // --- Step 1: Import seed fragment from --from <file> ---
+  // The file is a JSON object. If it contains a key matching <name>, that
+  // sub-object (type/driver/config) is used as the seed. Otherwise the file
+  // itself is treated as a config{} fragment.
+  let imported = null;
+  if (flags.from) {
+    const fromPath = require('path').resolve(root, flags.from);
+    if (!fsSync.existsSync(fromPath)) {
+      log.error(`--from: file not found: ${fromPath}`);
+      process.exitCode = 2;
+      return;
+    }
+    try {
+      const raw = JSON.parse(await fs.readFile(fromPath, 'utf8'));
+      if (raw && raw[name] && typeof raw[name] === 'object') {
+        imported = raw[name];
+      } else if (raw && (raw.type || raw.driver || raw.config)) {
+        imported = raw;
+      } else {
+        imported = { config: raw }; // treat entire file as config{}
+      }
+      log.dim(`imported seed from ${flags.from}`);
+    } catch (e) {
+      log.error(`--from: invalid JSON: ${e.message}`);
+      process.exitCode = 2;
+      return;
+    }
+  }
+
+  const interactive = isTty();
+  let type = flags.type || (imported && imported.type) || existing.type;
+  let driver = flags.driver || (imported && imported.driver) || existing.driver;
+
+  if (!type && interactive) type = await prompt(`type (intake|issue|vcs|ci|notify|kb|api|observability): `, existing.type);
+  if (!driver && interactive) driver = await prompt(`driver (local|confluence|weknora|smtp|github|...): `, existing.driver);
+  if (!type || !driver) { log.error('--type and --driver are required'); process.exitCode = 2; return; }
+
+  // --- Step 2: merge config from existing + imported + --config-*= flags ---
+  const config = {
+    ...(existing.config || {}),
+    ...((imported && imported.config) || {}),
+  };
+  for (const k of Object.keys(flags)) {
+    if (!k.startsWith('config-')) continue;
+    const ck = k.slice('config-'.length);
+    setConfigValue(config, ck, flags[k]);
+  }
+
+  // --- Step 3: interactive guided prompts (skipped if --no-prompt) ---
+  if (interactive && !flags.noPrompt) {
+    log.dim(`(press enter to keep existing values, prefix with 'env:' to use \${env:VAR})`);
+    const known = configHints(driver);
+    for (const hint of known) {
+      if (hint.help) log.dim(`  # ${hint.help}`);
+      const curVal = getConfigValue(config, hint.key);
+      const defShown = formatConfigValue(curVal, hint.default);
+      const suffix = hint.choices ? ` [${hint.choices.join(' | ')}]` : '';
+      const val = await prompt(`${hint.key}${hint.required ? '*' : ''}${suffix} = `, defShown);
+      if (val === '') continue;
+      if (hint.choices && !hint.choices.includes(val)) {
+        log.warn(`value "${val}" not in [${hint.choices.join(', ')}] — stored anyway`);
+      }
+      if (val.startsWith('env:')) setConfigValue(config, hint.key, `\${env:${val.slice(4)}}`);
+      else if (hint.cast === 'number') setConfigValue(config, hint.key, Number(val));
+      else if (hint.cast === 'boolean') setConfigValue(config, hint.key, /^(1|true|yes|y)$/i.test(val));
+      else setConfigValue(config, hint.key, val);
+    }
+  }
+
+  cur[name] = { type, driver, config };
+  await fs.mkdir(require('path').dirname(file), { recursive: true });
+  await fs.writeFile(file, JSON.stringify(cur, null, 2) + '\n', 'utf8');
+  await lifecycle.applySecureMode(file);
+  log.ok(`saved [${scope}]: ${name} -> ${file} (mode 0600)`);
+
+  if (interactive && !flags.noVerify) {
+    log.info('verifying ...');
+    await statusOne(root, name);
+  }
+}
+
+/**
+ * Catalogue of "one-line" provider presets driven by the wizard.
+ *
+ * Each entry maps to (type, driver, default name) so the wizard can:
+ *   1. Show a numbered list and let the user pick (or "all"/"none").
+ *   2. Reuse the existing `configHints(driver)` prompts.
+ *   3. Save under a sensible default name like "kb.weknora", "notify.smtp", etc.
+ *
+ * Adding a new driver = add an entry here + extend `configHints()`. No other
+ * wiring needed — the wizard auto-picks it up.
+ */
+const SETUP_PRESETS = [
+  { name: 'intake.confluence', type: 'intake', driver: 'confluence',
+    label: 'Intake — Confluence (内置，零外部依赖)',
+    hint:  '支持 Server/Data Center 和 Cloud；需要 baseUrl + PAT' },
+  { name: 'notify.smtp',      type: 'notify', driver: 'smtp',
+    label: 'Notify — Email via SMTP (任意 SMTP 服务器)',
+    hint:  '比如 smtp.exmail.qq.com / 465 / 用户名 / 应用密钥' },
+  { name: 'kb.weknora',       type: 'kb',     driver: 'weknora',
+    label: 'Knowledge base — WeKnora-compatible API',
+    hint:  '需要 endpoint + kbId + token,可走 ${env:WEKNORA_API_KEY}' },
+  { name: 'kb.git',           type: 'kb',     driver: 'git',
+    label: 'Knowledge base — 独立 Git 仓库（类 arb-knowledge 模式）',
+    hint:  '知识库是独立 GitLab/GitHub 项目；deposit --mr 会在那边建分支 + 创 MR' },
+  { name: 'ci.jenkins',       type: 'ci',     driver: 'jenkins',
+    label: 'CI — Jenkins build/deploy jobs',
+    hint:  '用于 devflow deploy 触发测试/预发 Jenkins job；凭证建议走 env:JENKINS_TOKEN' },
+  { name: 'api.yapi',         type: 'api',    driver: 'yapi',
+    label: 'API — YAPI contract sync',
+    hint:  '把 OpenAPI/Swagger 或接口说明同步到 YAPI；凭证建议走 env:YAPI_TOKEN' },
+  { name: 'observability.sls', type: 'observability', driver: 'sls',
+    label: 'Observability — Aliyun SLS log query',
+    hint:  '用于提测/verify 时按 traceId、requestId 或关键词检索测试环境日志' },
+  { name: 'observability.oss', type: 'observability', driver: 'oss',
+    label: 'Observability — OSS log/object lookup',
+    hint:  '用于从 OSS 归档日志或对象中检索提测证据' },
+];
+
+/**
+ * Interactive multi-provider wizard.  `devflow provider setup`.
+ *
+ * Flow:
+ *   1. List `SETUP_PRESETS` numbered; mark "[configured]" if already set.
+ *   2. Ask which to (re)configure: comma-separated indices, "all", or "none".
+ *   3. For each pick, run guided prompts via the same `configHints()` table
+ *      that `add()` uses — no new prompt code paths.
+ *   4. Save each entry to providers.json (default --scope=user) with chmod 0600.
+ *   5. Final pass: `statusOne()` per saved provider so the user sees green/red.
+ *
+ * Non-TTY:
+ *   Refuse early. Setup is wizard-only; for CI / scripted setups, use
+ *   `devflow provider add --no-prompt --type=… --driver=… --config-key=…`.
+ */
+async function setup(root, flags = {}) {
+  if (!isTty()) {
+    log.error('setup is interactive only; in non-TTY contexts use "devflow provider add --no-prompt ..."');
+    process.exitCode = 2;
+    return;
+  }
+
+  const { scope, file } = scopeFile(root, flags);
+  if (scope === 'user') await userconfig.ensureUserConfig();
+  let cur = {};
+  if (fsSync.existsSync(file)) {
+    try { cur = JSON.parse(await fs.readFile(file, 'utf8')); } catch { cur = {}; }
+  }
+
+  log.raw('');
+  log.raw('devflow provider setup — interactive wizard');
+  log.raw(`writing to: ${file}  (scope=${scope})`);
+  log.raw('');
+  log.raw('available providers:');
+  SETUP_PRESETS.forEach((p, i) => {
+    const marked = cur[p.name] ? ' [configured]' : '';
+    log.raw(`  ${String(i + 1).padStart(2)}. ${p.label}${marked}`);
+    if (p.hint) log.dim(`      ${p.hint}`);
+  });
+  log.raw('');
+
+  const sel = (await prompt('select (e.g. "1,3,5", "all", or "none"): ', 'all')).trim();
+  const picks = parseSelection(sel, SETUP_PRESETS.length);
+  if (!picks.length) { log.info('nothing selected, exiting'); return; }
+
+  const saved = [];
+  for (const idx of picks) {
+    const p = SETUP_PRESETS[idx];
+    log.raw('');
+    log.raw(`── ${p.label} ──`);
+    if (cur[p.name]) {
+      const reuse = await prompt(`already configured. (k)eep / (e)dit / (s)kip: `, 'k');
+      if (/^s/i.test(reuse)) { log.dim('  skipped'); continue; }
+      if (/^k/i.test(reuse)) { log.dim('  kept as-is'); saved.push(p.name); continue; }
+    }
+    const existing = cur[p.name] || { config: {} };
+    const config = { ...(existing.config || {}) };
+
+    log.dim(`  (press enter to keep existing/default; prefix with "env:" to use \${env:VAR})`);
+    for (const hint of configHints(p.driver)) {
+      if (hint.help) log.dim(`  # ${hint.help}`);
+      const curVal = getConfigValue(config, hint.key);
+      const defShown = formatConfigValue(curVal, hint.default);
+      const suffix = hint.choices ? ` [${hint.choices.join(' | ')}]` : '';
+      const val = await prompt(`  ${hint.key}${hint.required ? '*' : ''}${suffix} = `, defShown);
+      if (val === '') {
+        if (hint.required && !defShown) {
+          log.warn(`  ${hint.key} is required; you can fill later via "devflow provider rotate ${p.name}"`);
+        }
+        continue;
+      }
+      if (hint.choices && !hint.choices.includes(val)) {
+        log.warn(`  value "${val}" not in [${hint.choices.join(', ')}] — stored anyway`);
+      }
+      if (val.startsWith('env:')) setConfigValue(config, hint.key, `\${env:${val.slice(4)}}`);
+      else if (hint.cast === 'number') setConfigValue(config, hint.key, Number(val));
+      else if (hint.cast === 'boolean') setConfigValue(config, hint.key, /^(1|true|yes|y)$/i.test(val));
+      else setConfigValue(config, hint.key, val);
+
+      // afterPrompt: field-level side-effect hook (e.g. open browser after baseUrl is entered)
+      if (typeof hint.afterPrompt === 'function') {
+        await hint.afterPrompt(val, config);
+      }
+    }
+    normalizeSetupConfig(p.driver, config);
+
+    cur[p.name] = { type: p.type, driver: p.driver, config };
+    saved.push(p.name);
+    log.ok(`  → ${p.name} ready`);
+  }
+
+  if (!saved.length) { log.info('no changes saved'); return; }
+
+  await fs.mkdir(require('path').dirname(file), { recursive: true });
+  await fs.writeFile(file, JSON.stringify(cur, null, 2) + '\n', 'utf8');
+  await lifecycle.applySecureMode(file);
+  log.raw('');
+  log.ok(`saved ${saved.length} provider(s) to ${file} (mode 0600)`);
+
+  if (!flags.noVerify) {
+    log.raw('');
+    log.info('verifying ...');
+    let bad = 0;
+    for (const n of saved) {
+      const s = await statusOne(root, n);
+      if (!s.ok) bad++;
+    }
+    if (bad > 0) {
+      log.raw('');
+      log.warn(`${bad}/${saved.length} provider(s) need attention`);
+      log.dim('  fix incomplete fields:  devflow provider rotate <name>');
+      log.dim('  re-run wizard:          devflow provider setup');
+      process.exitCode = 1;
+    } else {
+      log.raw('');
+      log.ok('all configured providers passed validation');
+    }
+  }
+
+  log.raw('');
+  log.dim('next:');
+  log.dim('  devflow provider list           # see what is configured');
+  log.dim('  devflow provider audit          # security check (plaintext tokens, file modes)');
+  log.dim('  devflow provider rotate <n>     # rotate token / fix specific field');
+}
+
+/**
+ * Parse a selection string from the wizard.
+ *   "all"            → all indices
+ *   "none" / ""      → []
+ *   "1,3,5" or "1 3" → [0,2,4] (0-based, dedup'd, in-range)
+ *
+ * Out-of-range / non-numeric entries are silently skipped (the wizard prints
+ * the menu again if nothing valid is picked, by virtue of an empty result).
+ */
+function parseSelection(input, count) {
+  const s = (input || '').trim().toLowerCase();
+  if (!s || s === 'none' || s === 'no' || s === 'n') return [];
+  if (s === 'all' || s === 'a' || s === '*') {
+    return Array.from({ length: count }, (_, i) => i);
+  }
+  const seen = new Set();
+  for (const tok of s.split(/[,\s]+/)) {
+    const n = parseInt(tok, 10);
+    if (Number.isFinite(n) && n >= 1 && n <= count) seen.add(n - 1);
+  }
+  return Array.from(seen).sort((a, b) => a - b);
+}
+
+function configHints(driver) {
+  switch (driver) {
+    case 'weknora':
+      return [
+        { key: 'endpoint',   required: true,  help: 'base URL of WeKnora (or WeKnora-compatible) server' },
+        { key: 'kb_id',      required: true,  help: 'target knowledge base UUID' },
+        { key: 'token',      required: true,  help: 'API key — prefer env:WEKNORA_API_KEY over literal' },
+        { key: 'idempotent', required: false, cast: 'boolean', choices: ['true', 'false'],
+          help: 'if true, upload does findByTitle→update-or-create (arb-style). Default: false.' },
+      ];
+    case 'smtp':
+      return [
+        { key: 'host',       required: true,  help: 'SMTP server hostname (e.g. smtp.exmail.qq.com)' },
+        { key: 'port',       required: false, cast: 'number', default: 465, help: 'SMTP port (465=SMTPS, 587=STARTTLS, 25=plain)' },
+        { key: 'secure',     required: false, cast: 'boolean', choices: ['true', 'false'],
+          help: 'true = implicit TLS (port 465). Auto-inferred from port if omitted.' },
+        { key: 'user',       required: true,  help: 'SMTP auth username; prefer env:SMTP_USER' },
+        { key: 'pass',       required: true,  help: 'SMTP auth password / app token; prefer env:SMTP_PASS' },
+        { key: 'authMethod', required: false, choices: ['auto', 'login', 'plain'],
+          help: 'AUTH method (default auto). Some servers reject one of LOGIN/PLAIN.' },
+        { key: 'from',       required: false, help: 'default From address; falls back to user' },
+        { key: 'defaults.to', required: false, help: 'default recipients for devflow deliver --notify; comma-separated emails' },
+        { key: 'defaults.cc', required: false, help: 'default CC recipients for devflow deliver --notify; comma-separated emails' },
+      ];
+    case 'notion':     return [{ key: 'token', required: true, help: 'Notion integration token' }, { key: 'database_id', required: false, help: 'target database ID' }];
+    case 'github':     return [{ key: 'token', required: true, help: 'GitHub PAT; prefer env:GITHUB_TOKEN' }, { key: 'repo', required: false, help: '<owner>/<name>' }];
+    case 'gitlab':     return [{ key: 'token', required: true, help: 'GitLab PAT; prefer env:GITLAB_TOKEN' }, { key: 'project_id', required: false, help: 'numeric project ID' }];
+    case 'jenkins':
+      return [
+        { key: 'baseUrl', required: false, help: 'Jenkins base URL; job URLs imported per project can omit this' },
+        { key: 'user',    required: false, help: 'Jenkins username; prefer env:JENKINS_USER' },
+        { key: 'token',   required: false, help: 'Jenkins API token; prefer env:JENKINS_TOKEN' },
+        { key: 'triggerMethod', required: false, choices: ['post', 'get'], help: 'default post; use get for legacy jobs that require query parameters' },
+        { key: 'jobDiscovery', required: false, cast: 'boolean', choices: ['true', 'false'], help: 'enable smart matching from project/git remote to likely Jenkins jobs' },
+      ];
+    case 'yapi':
+      return [
+        { key: 'baseUrl', required: true, help: 'YAPI base URL, e.g. https://yapi.corp.com' },
+        { key: 'token', required: true, help: 'YAPI project token; prefer env:YAPI_TOKEN' },
+        { key: 'projectId', required: false, help: 'YAPI project id, if token is not project-scoped' },
+        { key: 'categoryId', required: false, help: 'target category/menu id; optional' },
+        { key: 'syncPath', required: false, default: '/api/open/import_data', help: 'YAPI import endpoint path' },
+      ];
+    case 'sls':
+      return [
+        { key: 'endpoint', required: true, help: 'Aliyun SLS endpoint, e.g. cn-hangzhou.log.aliyuncs.com' },
+        { key: 'project', required: true, help: 'SLS project name' },
+        { key: 'logstore', required: true, help: 'SLS logstore name' },
+        { key: 'accessKeyId', required: true, help: 'prefer env:ALIYUN_ACCESS_KEY_ID' },
+        { key: 'accessKeySecret', required: true, help: 'prefer env:ALIYUN_ACCESS_KEY_SECRET' },
+        { key: 'queryCommand', required: false, help: 'optional local query command template; supports ${query}, ${traceId}, ${requestId}, ${since}, ${limit}' },
+      ];
+    case 'oss':
+      return [
+        { key: 'endpoint', required: true, help: 'Aliyun OSS endpoint' },
+        { key: 'bucket', required: true, help: 'OSS bucket name' },
+        { key: 'prefix', required: false, help: 'default log/object prefix' },
+        { key: 'accessKeyId', required: true, help: 'prefer env:ALIYUN_ACCESS_KEY_ID' },
+        { key: 'accessKeySecret', required: true, help: 'prefer env:ALIYUN_ACCESS_KEY_SECRET' },
+        { key: 'queryCommand', required: false, help: 'optional local query command template; supports ${query}, ${traceId}, ${requestId}, ${since}, ${limit}' },
+      ];
+    case 'feishu':     return [{ key: 'app_id', required: true }, { key: 'app_secret', required: true }];
+    case 'yuque':      return [{ key: 'token', required: true }, { key: 'namespace', required: true, help: '<user>/<repo>' }];
+    case 'confluence':
+      return [
+        {
+          key: 'baseUrl', required: true,
+          help: 'Confluence 实例根 URL（如 https://confluence.corp.com 或 https://myorg.atlassian.net）',
+          afterPrompt: (baseUrl) => {
+            const base = baseUrl.replace(/\/+$/, '');
+            log.raw('');
+            if (base.includes('.atlassian.net')) {
+              const patUrl = 'https://id.atlassian.com/manage/api-tokens';
+              log.info(`正在打开 Confluence Cloud API Token 页面…`);
+              log.dim(`  ${patUrl}`);
+              openBrowser(patUrl);
+            } else {
+              log.info(`请在浏览器里找到 Personal Access Tokens（按顺序尝试）：`);
+              log.raw(`    1) 右上角头像 → Profile → Personal Access Tokens`);
+              log.raw(`    2) ${base}/plugins/servlet/de.resolution.apitokenauth/token`);
+              log.raw(`    3) 若都没有，token 填密码 + user 填用户名（Basic Auth）`);
+              openBrowser(`${base}/plugins/servlet/de.resolution.apitokenauth/token`);
+            }
+            log.raw('');
+          },
+        },
+        { key: 'token',     required: true,  help: 'PAT 模式：粘贴 Personal Access Token\n  #   Basic Auth 模式（Confluence 较旧 / 无 PAT 插件）：填登录密码，并在下一项填用户名' },
+        { key: 'user',      required: false, help: 'Basic Auth 用户名（Confluence 登录名）；留空 = Bearer/PAT 模式（推荐）' },
+        { key: 'timeoutMs', required: false, cast: 'number', help: '每次请求超时(ms)，默认 15000' },
+      ];
+    case 'git':
+      return [
+        {
+          key: 'repoUrl', required: true,
+          help: '独立知识库仓库 Git clone URL\n  #   例：git@code.corp.com:group/arb-knowledge.git\n  #       https://github.com/org/kb.git',
+        },
+        {
+          key: 'localPath', required: true,
+          help: '本地 clone 缓存路径\n  #   推荐填绝对路径，如 ~/.devflow/kb/arb-knowledge',
+        },
+        {
+          key: 'targetBranch', required: false,
+          help: 'MR 目标分支，默认 main',
+        },
+        {
+          key: 'gitlabApiUrl', required: false,
+          help: 'GitLab API 根 URL（私有 GitLab）\n  #   如 https://code.corp.com/api/v4\n  #   留空 = 仅用 glab CLI 或 GitHub API',
+          afterPrompt: (v) => {
+            if (!v) return;
+            log.raw('');
+            log.info('接下来需要 GitLab Personal Access Token（至少 api 权限）：');
+            const base = v.replace(/\/api\/v4\/?$/, '');
+            openBrowser(`${base}/-/user_settings/personal_access_tokens`);
+            log.raw('');
+          },
+        },
+        {
+          key: 'gitlabToken', required: false,
+          help: 'GitLab API token；prefer env:GITLAB_TOKEN\n  #   权限：api（read_repository + write_repository + create_merge_requests）',
+        },
+        {
+          key: 'projectId', required: false,
+          help: 'GitLab project path（如 group/arb-knowledge）或数字 ID\n  #   可在仓库首页 → Settings → General 看到',
+        },
+        {
+          key: 'githubToken', required: false,
+          help: 'GitHub PAT（仓库在 GitHub 时填此项）；prefer env:GITHUB_TOKEN',
+        },
+        {
+          key: 'githubRepo', required: false,
+          help: 'GitHub 仓库 "owner/repo"（可从 repoUrl 自动解析，留空即可）',
+        },
+        {
+          key: 'mrReviewers', required: false,
+          help: '自动指定的 GitLab MR reviewer（逗号分隔 GitLab 用户名，可选）',
+        },
+      ];
+    default: return [];
+  }
+}
+
+function normalizeSetupConfig(driver, config) {
+  if (driver !== 'weknora') return config;
+  delete config.tag_id;
+  if (!config.tags) {
+    const { buildTagMap } = require('../../knowledge/categories.js');
+    config.tags = buildTagMap();
+  }
+  return config;
+}
+
+async function remove(root, name, flags = {}) {
+  if (!name) { log.error('usage: devflow provider remove <name> [--scope=user|project]'); process.exitCode = 2; return; }
+  const { scope, file } = scopeFile(root, flags);
+  if (!fsSync.existsSync(file)) { log.warn(`no providers.json at ${scope} scope (${file})`); return; }
+  const cur = JSON.parse(await fs.readFile(file, 'utf8'));
+  if (!cur[name]) { log.warn(`provider not found in ${scope} scope: ${name}`); return; }
+  delete cur[name];
+  await fs.writeFile(file, JSON.stringify(cur, null, 2) + '\n', 'utf8');
+  await lifecycle.applySecureMode(file);
+  log.ok(`removed [${scope}]: ${name}`);
+}
+
+async function relogin(root, name, flags) {
+  if (!name) { log.error('usage: df provider relogin <name> [--force]'); process.exitCode = 2; return; }
+  let p;
+  try { p = await providers.load(root, { name }); }
+  catch (e) { log.error(e.message); process.exitCode = 1; return; }
+  if (typeof p.login !== 'function') { log.warn(`${name} does not support login`); return; }
+  await p.login({ force: !!(flags.force), interactive: isTty() });
+  const v = await p.validate();
+  if (v.ok) log.ok(`${name}: re-login complete`);
+  else { log.error(`${name}: still ${v.reason}`); process.exitCode = 1; }
+}
+
+async function rotate(root, name, flags) {
+  if (!name) { log.error('usage: devflow provider rotate <name> [--scope=user|project] [--config-token=NEW]'); process.exitCode = 2; return; }
+  const { scope, file } = scopeFile(root, flags);
+  if (!fsSync.existsSync(file)) { log.error(`no providers.json at ${scope} scope (${file})`); process.exitCode = 1; return; }
+  const cur = JSON.parse(await fs.readFile(file, 'utf8'));
+  if (!cur[name]) { log.error(`not found in ${scope} scope: ${name}`); process.exitCode = 1; return; }
+    cur[name].config = cur[name].config || {};
+  // Apply --config-* overrides; for fields not supplied, prompt interactively.
+  let touched = 0;
+  for (const k of Object.keys(flags)) {
+    if (!k.startsWith('config-')) continue;
+    const ck = k.slice('config-'.length);
+    setConfigValue(cur[name].config, ck, flags[k]);
+    touched++;
+  }
+  if (touched === 0 && isTty()) {
+    log.info('no --config-* given; prompting for sensitive fields ...');
+    const driver = cur[name].driver;
+    for (const hint of configHints(driver)) {
+      if (!/token|secret|password|key|cookie|auth/i.test(hint.key)) continue;
+      const v = await prompt(`new ${hint.key} (or env:NAME, blank=keep): `);
+      if (v === '') continue;
+      setConfigValue(cur[name].config, hint.key, v.startsWith('env:') ? `\${env:${v.slice(4)}}` : v);
+      touched++;
+    }
+  }
+  if (touched === 0) { log.warn('nothing to rotate'); return; }
+  await fs.writeFile(file, JSON.stringify(cur, null, 2) + '\n', 'utf8');
+  await lifecycle.applySecureMode(file);
+  log.ok(`rotated ${touched} field(s) on ${name}`);
+  await statusOne(root, name);
+}
+
+function getConfigValue(config, key) {
+  return String(key).split('.').reduce((acc, part) => (
+    acc && typeof acc === 'object' ? acc[part] : undefined
+  ), config);
+}
+
+function setConfigValue(config, key, value) {
+  const parts = String(key).split('.');
+  let cur = config;
+  for (let i = 0; i < parts.length - 1; i++) {
+    const part = parts[i];
+    if (!cur[part] || typeof cur[part] !== 'object' || Array.isArray(cur[part])) cur[part] = {};
+    cur = cur[part];
+  }
+  cur[parts[parts.length - 1]] = value;
+}
+
+function formatConfigValue(value, fallback) {
+  if (Array.isArray(value)) return value.join(',');
+  if (value !== undefined && value !== null) return String(value);
+  return fallback !== undefined ? String(fallback) : '';
+}
+
+async function logout(root, name) {
+  if (!name) { log.error('usage: df provider logout <name>'); process.exitCode = 2; return; }
+  let p;
+  try { p = await providers.load(root, { name }); }
+  catch (e) { log.error(e.message); process.exitCode = 1; return; }
+  if (typeof p.logout !== 'function') { log.warn('provider has no logout'); return; }
+  await p.logout();
+  log.ok(`${name}: logged out`);
+}
+
+async function audit(root) {
+  const findings = await lifecycle.securityCheck(root);
+  if (!findings.length) { log.ok('no security issues'); return; }
+  for (const f of findings) {
+    const tag = f.severity === 'error' ? '[err]' : f.severity === 'warn' ? '[warn]' : '[info]';
+    log.raw(`${tag} ${f.file}\n       ${f.message}${f.fix ? `  (fix: ${f.fix})` : ''}`);
+  }
+  process.exitCode = findings.some((f) => f.severity === 'error') ? 1 : 0;
+}
+
+function prompt(q, def = '') {
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    const showDef = def ? ` [${def}]` : '';
+    rl.question(`${q}${showDef}`, (ans) => {
+      rl.close();
+      resolve((ans || '').trim() || def);
+    });
+  });
+}
+
+function isTty() { return !!(process.stdin && process.stdin.isTTY && process.stdout && process.stdout.isTTY); }
+
+function openBrowser(url) {
+  const { spawnSync } = require('child_process');
+  try {
+    if (process.platform === 'darwin')      spawnSync('open',     [url],               { stdio: 'ignore' });
+    else if (process.platform === 'win32')  spawnSync('cmd',      ['/c','start','',url],{ stdio: 'ignore', shell: true });
+    else                                    spawnSync('xdg-open', [url],               { stdio: 'ignore' });
+  } catch { /* ignore */ }
+}
+
+function help() {
+  log.raw(`devflow provider <list|status|setup|add|remove|relogin|rotate|logout|audit> [args]
+
+  setup                             interactive wizard — pick which providers to set up,
+                                    fill credentials step by step (recommended for first run)
+  list                              show configured providers (merged: user + project)
+  status [<name>]                   validate one (or all) — exit 1 if any not ok
+  add <name> [--scope=user|project] [--type=<t>] [--driver=<d>]
+             [--config-key=val] [--no-prompt] [--from=<file.json>]
+  remove <name> [--scope=user|project]
+  relogin <name> [--force]          run provider.login() then validate
+  rotate <name> [--scope=user|project] [--config-key=val]
+  logout <name>                     drop session if provider supports it
+  audit                             scan providers.json for plaintext secrets / weak modes
+
+Scope:
+  --scope=user (default)   ~/.devflow/providers.json          one source of truth across projects
+  --scope=project          <repo>/devflow/providers.json      repo-specific overrides
+
+Examples:
+  devflow provider setup                                             # ★ recommended first-time flow
+  devflow provider setup --scope=project                             # repo-only wizard
+  devflow provider add kb.weknora                                    # user-scope, guided prompts
+  devflow provider add kb.weknora --from ./weknora-arb.local.json    # arb-shape seed file
+  devflow provider add notify.smtp                                   # user-scope SMTP setup
+  devflow provider add kb.weknora-staging --scope=project            # repo-only override
+`);
+}
+
+module.exports = { run, parseSelection, SETUP_PRESETS };