@chenguangyao/devflow-kit 0.1.43

package/src/cli/commands/switch.js

@@ -0,0 +1,27 @@
+'use strict';
+const log = require('../../utils/log.js');
+const config = require('../../core/config.js');
+const initCmd = require('./init.js');
+
+async function run({ sub, positional = [], flags = {}, cwd }) {
+  const root = cwd || process.cwd();
+  const what = sub || positional[0];
+  if (what !== 'project-overview') {
+    log.error('usage: devflow switch project-overview --mode=<reference|supplement|generate>');
+    process.exitCode = 2; return;
+  }
+  const mode = flags.mode;
+  if (!['reference', 'supplement', 'generate'].includes(mode)) {
+    log.error('--mode must be reference|supplement|generate');
+    process.exitCode = 2; return;
+  }
+  const cfg = await config.ensure(root);
+  cfg.projectOverview = cfg.projectOverview || {};
+  cfg.projectOverview.mode = mode;
+  await config.write(root, cfg);
+  log.ok(`projectOverview.mode = ${mode}`);
+  log.info('refreshing IDE marker sections...');
+  await initCmd.run({ flags: { 'overview-mode': mode }, cwd: root });
+}
+
+module.exports = { run };

package/src/cli/commands/sync.js

@@ -0,0 +1,47 @@
+'use strict';
+const log = require('../../utils/log.js');
+const initCmd = require('./init.js');
+const fs = require('fs/promises');
+const path = require('path');
+const providers = require('../../providers/loader.js');
+
+async function run({ sub, positional = [], flags = {}, cwd }) {
+  const what = sub || positional[0];
+  if (what === 'yapi') return syncYapi({ root: cwd || process.cwd(), flags, positional });
+  if (what !== 'project') {
+    log.error('usage: devflow sync <project|yapi> [--check]');
+    process.exitCode = 2; return;
+  }
+  if (flags.check) {
+    log.info('check mode: re-detect overview source and report drift only (NYI in v0.1; runs as full sync).');
+  }
+  // Re-run init to refresh marker sections (idempotent)
+  await initCmd.run({ flags, cwd });
+}
+
+async function syncYapi({ root, flags = {}, positional = [] }) {
+  const file = flags.file || positional[1] || flags.contract || flags.openApi || flags['open-api'];
+  if (!file) {
+    log.error('usage: devflow sync yapi --file=<openapi.json|swagger.json|api.md> [--provider=api.yapi] [--dry-run]');
+    process.exitCode = 2;
+    return;
+  }
+  const abs = path.resolve(root, file);
+  const content = await fs.readFile(abs, 'utf8');
+  const api = await providers.load(root, flags.provider ? { name: flags.provider } : { type: 'api' });
+  if (typeof api.syncContract !== 'function') {
+    log.error(`provider ${api.name || api.driver} does not support YAPI contract sync`);
+    process.exitCode = 1;
+    return;
+  }
+  const result = await api.syncContract({
+    file: abs,
+    content,
+    dryRun: flags.dryRun === true || flags['dry-run'] === true,
+  });
+  log.ok(`yapi sync: ${result.status}  interfaces=${result.interfaces}`);
+  if (result.title) log.dim(`title: ${result.title}`);
+  if (result.response) log.raw(JSON.stringify(result.response, null, 2));
+}
+
+module.exports = { run, _internals: { syncYapi } };

package/src/cli/commands/test.js

@@ -0,0 +1,366 @@
+'use strict';
+const fs = require('fs/promises');
+const fsSync = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+const log = require('../../utils/log.js');
+const paths = require('../../core/paths.js');
+const change = require('../../core/change.js');
+const templates = require('../../templates/index.js');
+const helpers = require('./_helpers.js');
+const detect = require('../../reports/detect.js');
+const parser = require('../../reports/parse.js');
+const cov = require('../../reports/coverage.js');
+const projects = require('../../core/projects.js');
+const aggregate = require('../../reports/aggregate.js');
+
+const KINDS = new Set(['unit', 'integration', 'contract', 'e2e', 'joint', 'remote', 'smoke', 'regression', 'perf']);
+
+async function run({ sub, flags = {}, positional = [], cwd }) {
+  const root = cwd || process.cwd();
+  const kind = sub || positional[0];
+  if (!KINDS.has(kind)) {
+    log.error(`usage: devflow test <${[...KINDS].join('|')}> [--cmd "<your test command>"] [--framework=<auto|jest|...>]`);
+    process.exitCode = 2; return;
+  }
+  const slug = await helpers.resolveSlug(root, flags, []);
+  if (!slug) { process.exitCode = 1; return; }
+  const st = await helpers.loadStateOrFail(root, slug);
+  if (!st) { process.exitCode = 1; return; }
+
+  const reportsDir = await change.ensureSubdir(root, slug, 'reports');
+
+  // Decide command + framework.
+  let cmd = flags.cmd || flags.command;
+  let framework = flags.framework || flags.fw;
+  let coverageHint = null;
+
+  if (!cmd && kind !== 'unit' && flags.project) {
+    const resolved = await projects.resolveTestCommand({
+      project: flags.project,
+      env: flags.env || flags.environment || 'test',
+      kind,
+      api: flags.api === true || flags.api === 'true',
+    });
+    if (resolved.command) {
+      cmd = resolved.command;
+      if (!framework) framework = resolved.framework;
+    }
+  }
+
+  if ((!cmd || !framework) && kind === 'unit') {
+    const detected = detect.detect(root);
+    const first = detected[0];
+    if (first) {
+      if (!cmd) cmd = first.command;
+      if (!framework) framework = first.framework;
+      coverageHint = first.coverageHint;
+    }
+  }
+  if (!framework) framework = 'generic';
+
+  const backendUrl = flags.backendUrl || flags['backend-url'] || flags.backend || '';
+  const frontendUrl = flags.frontendUrl || flags['frontend-url'] || flags.frontend || '';
+  const apiBaseUrl = flags.apiBaseUrl || flags['api-base-url'] || flags.api || flags.url || '';
+  const database = flags.database || flags.db || '-';
+  const wantsPreflight = flags.preflight === true || flags['preflight'] === true;
+
+  let preflight = null;
+  if (kind === 'joint' && wantsPreflight) {
+    preflight = runJointPreflight({ backendUrl, frontendUrl });
+    await writePreflightLog(reportsDir, 'joint-preflight.log', preflight);
+    if (!preflight.ok) {
+      await writeKindReport({
+        kind, reportsDir, slug, status: 'blocked', failureType: 'env_error',
+        total: null, passed: null, failed: null, coverage: null,
+        command: cmd || '(未执行:联调预检未通过)',
+        output: renderPreflightOutput(preflight),
+        backendUrl, frontendUrl, apiBaseUrl, database,
+        preflight,
+        splitReport: wantsSplitReport(flags),
+      });
+      log.error(`joint preflight blocked: ${preflight.errors.join('; ')}`);
+      log.dim('fix environment/browser tooling, then rerun devflow test joint --preflight ...');
+      process.exitCode = 1;
+      return;
+    }
+  } else if (kind === 'remote' && wantsPreflight) {
+    preflight = runRemotePreflight({ apiBaseUrl });
+    await writePreflightLog(reportsDir, 'remote-preflight.log', preflight);
+    if (!preflight.ok) {
+      await writeKindReport({
+        kind, reportsDir, slug, status: 'blocked', failureType: 'env_error',
+        total: null, passed: null, failed: null, coverage: null,
+        command: cmd || '(未执行:远程 API 预检未通过)',
+        output: renderPreflightOutput(preflight),
+        backendUrl, frontendUrl, apiBaseUrl, database,
+        preflight,
+        splitReport: wantsSplitReport(flags),
+      });
+      log.error(`remote preflight blocked: ${preflight.errors.join('; ')}`);
+      log.dim('fix test environment URL/connectivity, then rerun devflow test remote --preflight ...');
+      process.exitCode = 1;
+      return;
+    }
+  }
+
+  // For non-unit kinds, --cmd is required (no auto-detect).
+  if (!cmd && kind !== 'unit') {
+    log.error(`no command. pass --cmd "<your ${kind} command>"`);
+    process.exitCode = 2; return;
+  }
+
+  let stdout = '(未运行命令;请在下方手动补充输出)';
+  let runStatus = 'pending';
+  let exitCode = null;
+  if (cmd) {
+    log.info(`framework=${framework}  > ${cmd}`);
+    const r = spawnSync(cmd, { shell: true, encoding: 'utf8', maxBuffer: 16 * 1024 * 1024, cwd: root });
+    stdout = ((r.stdout || '') + (r.stderr || ''));
+    exitCode = r.status;
+    runStatus = exitCode === 0 ? 'pass' : 'fail';
+  }
+
+  // Parse stdout.
+  const parsed = parser.parse(framework, stdout);
+  const truncatedOutput = truncate(stdout, 12000);
+
+  // Discover coverage (unit only by default).
+  let coverage = null;
+  if (kind === 'unit') {
+    coverage = cov.discover(root, coverageHint);
+  }
+
+  // status: prefer explicit pass/fail from command exit code; if unknown, infer from parsed numbers.
+  let status = runStatus;
+  if (status === 'pending' && parsed.failed != null) {
+    status = parsed.failed > 0 ? 'fail' : 'pass';
+  }
+  const failureType = classifyFailureType({
+    explicit: flags.failureType || flags['failure-type'],
+    status,
+    preflight,
+    exitCode,
+  });
+
+  await writeKindReport({
+    kind,
+    reportsDir,
+    slug,
+    status,
+    failureType,
+    total: parsed.total,
+    passed: parsed.passed,
+    failed: parsed.failed,
+    coverage: coverage && coverage.lines ? `${coverage.lines.pct}%` : '-',
+    command: cmd || '(未执行)',
+    output: truncatedOutput,
+    backendUrl,
+    frontendUrl,
+    apiBaseUrl,
+    database,
+    preflight,
+    framework,
+    parsed,
+    coverageDetails: coverage,
+    exitCode,
+    splitReport: wantsSplitReport(flags),
+  });
+  log.ok(`reports/test-report.md#${kind}  status=${status}${failureType !== '-' ? `  failureType=${failureType}` : ''}  ${parsed.total != null ? `passed=${parsed.passed}/${parsed.total}` : ''}${coverage && coverage.lines ? `  cov=${coverage.lines.pct}%` : ''}`);
+}
+
+async function writeKindReport({
+  kind, reportsDir, slug, status, failureType, total, passed, failed, coverage,
+  command, output, backendUrl, frontendUrl, apiBaseUrl, database,
+  preflight, framework = 'generic', parsed = {}, coverageDetails = null, exitCode = null,
+  splitReport = false,
+}) {
+  const tplName = `reports/${kind}-test.md`;
+  let tpl;
+  try { tpl = await templates.load(tplName); }
+  catch { tpl = `---\nslug: \${slug}\nkind: \${kind}\nstatus: \${status}\nfailureType: \${failureType}\nts: \${date}\n---\n\n# ${kind} 测试报告\n\n## 命令\n\n\`\`\`\n\${command}\n\`\`\`\n\n## 输出\n\n\`\`\`\n\${output}\n\`\`\`\n`; }
+
+  const body = templates.render(tpl, {
+    slug,
+    kind,
+    status,
+    failureType: failureType || '-',
+    total:    fmt(total),
+    passed:   fmt(passed),
+    failed:   fmt(failed),
+    coverage: coverage || '-',
+    command,
+    output,
+    backendUrl: backendUrl || '-',
+    frontendUrl: frontendUrl || '-',
+    apiBaseUrl: apiBaseUrl || '-',
+    database: database || '-',
+    preflightTool: preflight && preflight.tool ? preflight.tool : '-',
+    preflightStatus: preflight ? (preflight.ok ? 'pass' : 'blocked') : '-',
+    preflightDetail: preflight ? renderPreflightOutput(preflight) : '-',
+    date: new Date().toISOString(),
+  });
+  let final = body;
+
+  // Append a structured "failures" section + coverage details.
+  const detail = renderDetail(framework, parsed, coverageDetails, exitCode, failureType);
+  if (detail) final = final.replace(/\n*$/, '\n') + '\n' + detail + '\n';
+
+  await aggregate.upsertReport({
+    reportsDir,
+    slug,
+    title: slug,
+    kind,
+    body: final,
+    meta: { status, total, passed, failed, coverage, failureType },
+  });
+  if (splitReport) {
+    const file = path.join(reportsDir, `${kind}-test.md`);
+    await fs.writeFile(file, final, 'utf8');
+  }
+}
+
+function fmt(n) { return n == null ? '-' : String(n); }
+
+function renderDetail(framework, p, c, exitCode, failureType) {
+  const lines = [];
+  lines.push('## 解析详情');
+  lines.push('');
+  lines.push(`- 测试框架: \`${framework}\``);
+  if (failureType && failureType !== '-') lines.push(`- 失败类型: \`${failureType}\``);
+  if (exitCode != null) lines.push(`- 退出码: ${exitCode}`);
+  if (p.duration_ms != null) lines.push(`- 耗时: ${p.duration_ms} ms`);
+  if (p.skipped != null) lines.push(`- 跳过数: ${p.skipped}`);
+  if (p.failures && p.failures.length) {
+    lines.push('');
+    lines.push('### 失败用例');
+    for (const f of p.failures.slice(0, 30)) {
+      lines.push(`- ${f.name}${f.file ? ` (${f.file})` : ''}`);
+    }
+    if (p.failures.length > 30) lines.push(`- 另有 ${p.failures.length - 30} 个失败用例未展开`);
+  }
+  if (c) {
+    lines.push('');
+    lines.push('### 覆盖率');
+    lines.push(`- 来源: \`${c.format}\``);
+    if (c.lines)      lines.push(`- 行覆盖率: ${c.lines.pct}% (${c.lines.covered ?? '?'}/${c.lines.total ?? '?'})`);
+    if (c.branches)   lines.push(`- 分支覆盖率: ${c.branches.pct}% (${c.branches.covered ?? '?'}/${c.branches.total ?? '?'})`);
+    if (c.functions)  lines.push(`- 函数覆盖率: ${c.functions.pct}% (${c.functions.covered ?? '?'}/${c.functions.total ?? '?'})`);
+    if (c.statements) lines.push(`- 语句覆盖率: ${c.statements.pct}% (${c.statements.covered ?? '?'}/${c.statements.total ?? '?'})`);
+  }
+  return lines.join('\n');
+}
+
+function classifyFailureType({ explicit, status, preflight, exitCode }) {
+  if (explicit && explicit !== true) return String(explicit);
+  if (status === 'blocked') return 'env_error';
+  if (preflight && !preflight.ok) return 'env_error';
+  if (status === 'fail' || (exitCode != null && exitCode !== 0)) return 'code_error';
+  return '-';
+}
+
+function wantsSplitReport(flags = {}) {
+  return flags.splitReport === true
+    || flags['split-report'] === true
+    || flags.rawReport === true
+    || flags['raw-report'] === true;
+}
+
+function runJointPreflight({ backendUrl, frontendUrl }) {
+  const out = { mode: 'joint', ok: true, tool: null, checks: [], errors: [] };
+  const tool = detectBrowserTool();
+  out.tool = tool || null;
+  out.checks.push({ name: 'browser-tool', status: tool ? 'pass' : 'blocked', detail: tool || '未发现 agent-browser / chrome-devtools-mcp / playwright' });
+  if (!tool) out.errors.push('browser automation tool not found');
+  for (const [name, url] of [['backend-url', backendUrl], ['frontend-url', frontendUrl]]) {
+    const check = checkUrlReachable(url);
+    out.checks.push({ name, ...check });
+    if (check.status !== 'pass') out.errors.push(`${name} ${check.detail}`);
+  }
+  out.ok = out.errors.length === 0;
+  return out;
+}
+
+function runRemotePreflight({ apiBaseUrl }) {
+  const out = { mode: 'remote', ok: true, tool: 'http', checks: [], errors: [] };
+  const check = checkUrlReachable(apiBaseUrl);
+  out.checks.push({ name: 'api-base-url', ...check });
+  if (check.status !== 'pass') out.errors.push(`api-base-url ${check.detail}`);
+  out.ok = out.errors.length === 0;
+  return out;
+}
+
+function detectBrowserTool() {
+  if (commandExists('agent-browser')) return 'agent-browser';
+  if (commandExists('chrome-devtools-mcp')) return 'chrome-devtools-mcp';
+  if (commandExists('playwright')) return 'playwright';
+  if (commandExists('npx') && spawnSync('npx', ['--no-install', 'playwright', '--version'], { encoding: 'utf8', timeout: 3000 }).status === 0) {
+    return 'playwright';
+  }
+  return null;
+}
+
+function commandExists(name) {
+  const r = spawnSync('sh', ['-lc', `command -v ${shellQuote(name)}`], { encoding: 'utf8' });
+  return r.status === 0;
+}
+
+function shellQuote(s) {
+  return `'${String(s).replace(/'/g, `'\\''`)}'`;
+}
+
+function checkUrlReachable(url) {
+  if (!url) return { status: 'blocked', detail: 'missing url' };
+  const cmd = `curl -I -L --max-time 5 -o /dev/null -s -w "%{http_code}" ${shellQuote(url)}`;
+  const r = spawnSync('sh', ['-lc', cmd], { encoding: 'utf8', timeout: 7000 });
+  if (r.status !== 0) return { status: 'blocked', detail: (r.stderr || r.stdout || 'curl failed').trim() };
+  const code = Number((r.stdout || '').trim());
+  if (code >= 200 && code < 500) return { status: 'pass', detail: `HTTP ${code}` };
+  return { status: 'blocked', detail: `HTTP ${code || 'unknown'}` };
+}
+
+async function writePreflightLog(reportsDir, fileName, preflight) {
+  const lines = [
+    `# ${preflight.mode} preflight`,
+    '',
+    `- status: ${preflight.ok ? 'pass' : 'blocked'}`,
+    `- tool: ${preflight.tool || '-'}`,
+    '',
+    '| 检查项 | 状态 | 详情 |',
+    '| --- | --- | --- |',
+  ];
+  for (const c of preflight.checks || []) lines.push(`| ${c.name} | ${c.status} | ${String(c.detail || '-').replace(/\|/g, '\\|')} |`);
+  if (preflight.errors.length) {
+    lines.push('', '## 阻塞原因', '');
+    for (const e of preflight.errors) lines.push(`- ${e}`);
+  }
+  await fs.writeFile(path.join(reportsDir, fileName), lines.join('\n') + '\n', 'utf8');
+}
+
+function renderPreflightOutput(preflight) {
+  return [
+    `mode=${preflight.mode}`,
+    `status=${preflight.ok ? 'pass' : 'blocked'}`,
+    `tool=${preflight.tool || '-'}`,
+    ...((preflight.checks || []).map((c) => `${c.name}: ${c.status} (${c.detail || '-'})`)),
+    ...((preflight.errors || []).map((e) => `error: ${e}`)),
+  ].join('\n');
+}
+
+function truncate(s, max) {
+  const text = String(s || '');
+  return text.length > max ? text.slice(0, max) + `\n... [${text.length - max} bytes truncated]` : text;
+}
+
+module.exports = {
+  run,
+  _internals: {
+    classifyFailureType,
+    truncate,
+    wantsSplitReport,
+    detectBrowserTool,
+    checkUrlReachable,
+    runJointPreflight,
+    runRemotePreflight,
+  },
+};

package/src/cli/commands/uninstall.js

@@ -0,0 +1,32 @@
+'use strict';
+const fs = require('fs/promises');
+const path = require('path');
+const log = require('../../utils/log.js');
+const paths = require('../../core/paths.js');
+const markers = require('../../core/markers.js');
+
+const TARGETS = [
+  '.claude/CLAUDE.md',
+  '.cursor/rules/devflow.mdc',
+  'AGENTS.md',
+];
+
+async function run({ flags = {}, cwd }) {
+  const root = cwd || process.cwd();
+  for (const rel of TARGETS) {
+    const file = path.join(root, rel);
+    const removedA = await markers.removeSection(file, 'project-overview');
+    const removedB = await markers.removeSection(file, 'workflow');
+    if (removedA || removedB) log.ok(`unmarked: ${rel}`);
+  }
+  if (flags.purge) {
+    const dir = paths.devflowDir(root);
+    log.warn(`--purge: removing ${dir}`);
+    await fs.rm(dir, { recursive: true, force: true });
+    log.ok(`removed devflow/`);
+  } else {
+    log.dim('devflow/ kept. add --purge to remove all change/spec/knowledge data.');
+  }
+}
+
+module.exports = { run };

package/src/cli/commands/update.js

@@ -0,0 +1,74 @@
+'use strict';
+const fs = require('fs/promises');
+const fsSync = require('fs');
+const path = require('path');
+const log = require('../../utils/log.js');
+const markers = require('../../core/markers.js');
+const initCmd = require('./init.js');
+
+const IDE_TARGETS = {
+  claude: '.claude/CLAUDE.md',
+  cursor: '.cursor/rules/devflow.mdc',
+  agents: 'AGENTS.md',
+};
+
+/**
+ * `devflow update`
+ *   Default mode  → idempotent re-init (refreshes marker sections only).
+ *
+ * `devflow update --ide-clean`
+ *   Strip every devflow-managed marker section (`workflow`, `project-overview`)
+ *   from the IDE marker files in the current repo. If the file becomes empty
+ *   (only whitespace / our markers were the entire file), remove it.
+ *   Useful after switching from `--ide=full` to `--ide=auto/minimal` —
+ *   `init` warns about stale markers; this is the cleanup tool.
+ */
+async function run(ctx) {
+  const flags = ctx.flags || {};
+  if (flags['ide-clean'] === true || flags.ideClean === true) {
+    return cleanIdeMarkers(ctx.cwd || process.cwd());
+  }
+  return initCmd.run(ctx);
+}
+
+async function cleanIdeMarkers(root) {
+  let cleaned = 0;
+  let removed = 0;
+  for (const rel of Object.values(IDE_TARGETS)) {
+    const file = path.join(root, rel);
+    if (!fsSync.existsSync(file)) continue;
+
+    const beforeSize = (await fs.stat(file)).size;
+    const removedWorkflow = await markers.removeSection(file, 'workflow');
+    const removedOverview = await markers.removeSection(file, 'project-overview');
+    if (!removedWorkflow && !removedOverview) continue;
+    cleaned++;
+
+    // If the file is now effectively empty (whitespace only), drop it. This
+    // matters most for files devflow created (.cursor/rules/devflow.mdc) which
+    // have no other reason to exist.
+    let body;
+    try { body = await fs.readFile(file, 'utf8'); } catch { body = ''; }
+    if (!body.trim()) {
+      try {
+        await fs.unlink(file);
+        removed++;
+        log.ok(`removed empty file: ${rel}`);
+      } catch (e) {
+        log.warn(`could not remove ${rel}: ${e.message}`);
+      }
+    } else {
+      const afterSize = (await fs.stat(file)).size;
+      log.ok(`cleaned markers from: ${rel}  (${beforeSize}B → ${afterSize}B)`);
+    }
+  }
+  if (cleaned === 0) {
+    log.info('no devflow markers found in IDE files; nothing to clean');
+    return;
+  }
+  log.raw('');
+  log.ok(`cleanup complete: ${cleaned} file(s) touched, ${removed} removed entirely`);
+  log.dim('  re-run `devflow init` to regenerate (will follow current --ide mode)');
+}
+
+module.exports = { run, cleanIdeMarkers };