@chenguangyao/devflow-kit 0.1.43

package/src/cli/commands/deliver.js

@@ -0,0 +1,377 @@
+'use strict';
+const fs = require('fs/promises');
+const fsSync = require('fs');
+const path = require('path');
+const log = require('../../utils/log.js');
+const paths = require('../../core/paths.js');
+const state = require('../../core/state.js');
+const change = require('../../core/change.js');
+const checkpoint = require('../../core/checkpoint.js');
+const providers = require('../../providers/loader.js');
+const helpers = require('./_helpers.js');
+const doctor = require('./doctor.js');
+const config = require('../../core/config.js');
+const autodetect = require('../../core/autodetect.js');
+const submit = require('./_submit.js');
+const aggregate = require('../../reports/aggregate.js');
+
+async function run({ flags = {}, positional = [], cwd }) {
+  const root = cwd || process.cwd();
+  const slug = await helpers.resolveSlug(root, flags, positional);
+  if (!slug) { process.exitCode = 1; return; }
+  const st = await helpers.loadStateOrFail(root, slug);
+  if (!st) { process.exitCode = 1; return; }
+  if (helpers.blockWorkflowStep(root, st, slug, 'deliver', 'deliver')) return;
+
+  if (await blockPendingRiskCheckpoint(root, slug, st, flags)) return;
+  if (await blockOpenRiskSignals(root, slug, st, flags)) return;
+
+  // Preflight: verify phase must be completed
+  const verifyPhase = st.phases && st.phases.verify;
+  if (!verifyPhase || verifyPhase.status !== 'completed') {
+    log.error('verify phase not completed. run "devflow verify finalize" first.');
+    process.exitCode = 1;
+    return;
+  }
+
+  // Preflight: review phase must be completed (redundant, but explicit)
+  const reviewPhase = st.phases && st.phases.review;
+  if (!reviewPhase || reviewPhase.status !== 'completed') {
+    log.error(`deliver blocked: review.status=${(reviewPhase && reviewPhase.status) || 'pending'}. finish review first.`);
+    process.exitCode = 1;
+    return;
+  }
+
+  // Preflight: devflow doctor --scope change,git,cred (continue only if no errors, unless --skip-doctor with reason)
+  const skipDoctor = flags['skip-doctor'] === true || flags.skipDoctor === true;
+  if (!skipDoctor) {
+    const { findings, errors } = await doctor.audit(root, ['change', 'git', 'cred']);
+    if (errors > 0) {
+      log.error('deliver blocked: devflow doctor found errors:');
+      for (const f of findings) {
+        if (f.level === 'error') log.error(`  [${f.scope}] ${f.msg}`);
+        else if (f.level === 'warn') log.warn(`  [${f.scope}] ${f.msg}`);
+      }
+      log.dim('fix the errors, or override (audited): devflow deliver --skip-doctor --reason="..."');
+      process.exitCode = 1;
+      return;
+    }
+  } else {
+    const reason = flags.reason;
+    if (!reason || reason === true) {
+      log.error('--skip-doctor requires --reason="..." (audited)');
+      process.exitCode = 2;
+      return;
+    }
+    state.logEvent(st, 'deliver.skip_doctor', { reason });
+    log.warn(`doctor preflight skipped — reason: "${reason}"`);
+  }
+
+  const mode = flags.mode || positional[1] || 'pr';
+  const isMicro = st.mode === 'micro' || st.level === 'L0';
+  log.info(`deliver mode=${mode}`);
+
+  // Resolve detect / branches once — used by both PR and notify paths
+  const cfg = await config.read(root).catch(() => null);
+  const detect = (cfg && cfg.detect) || (await autodetect.detect(root).catch(() => null)) || {};
+  const base = flags.base
+    || (cfg && cfg.detect && cfg.detect.defaultBranch)
+    || autodetect.detectDefaultBranch(root)
+    || 'main';
+  const head = flags.head || submit.primaryProjectBranch(st) || submit.currentBranch(root) || '';
+
+  // ─── PR description body ────────────────────────────────────────────────
+  // For PR / MR: keep self-test embed + doc links (reviewers want diffs not full submit doc).
+  const cdir = change.resolveChangeDir(root, slug);
+  const selfTestPath = path.join(cdir, 'reports', 'self-test.md');
+  const aggregateSelfTest = aggregate.readAggregate(path.join(cdir, 'reports')).reports.find((r) => r.kind === 'self-test');
+  let prBody = `# ${st.title || slug}\n\n`;
+  prBody += `> change: \`${slug}\`  level: \`${st.level}\`  base ← head: \`${base}\` ← \`${head || '(current)'}\`\n\n`;
+  if (aggregateSelfTest || fsSync.existsSync(selfTestPath)) {
+    prBody += `## 提测自测\n\n`;
+    prBody += aggregateSelfTest ? aggregateSelfTest.body : await fs.readFile(selfTestPath, 'utf8');
+    prBody += `\n`;
+  }
+  prBody += `\n## 关联文档\n\n`;
+  for (const f of ['proposal.md', 'requirement.md', 'design.md', 'plan.md', 'review.md', 'verify.md']) {
+    if (fsSync.existsSync(path.join(cdir, f))) {
+      prBody += `- [\`${f}\`](devflow/changes/${slug}/${f})\n`;
+    }
+  }
+
+  if (mode === 'pr') {
+    let vcs;
+    try { vcs = await providers.load(root, { type: 'vcs' }); }
+    catch (e) { log.error(e.message); process.exitCode = 1; return; }
+    const result = await vcs.pr({
+      title: `[${slug}] ${st.title || slug}`,
+      body_md: prBody,
+      base, head,
+      draft: flags.draft === true,
+    });
+    if (result.url) log.ok(`PR: ${result.url}`);
+  } else if (mode === 'merge') {
+    log.warn('merge mode is a stub in v0.1; merge manually then run "devflow archive" to merge specs and deposit knowledge.');
+  } else if (mode === 'keep') {
+    log.info('keeping change open. run "devflow deliver --mode=pr" later.');
+  } else if (mode === 'discard') {
+    log.warn('discard mode is a stub. delete devflow/changes/<slug>/ manually.');
+  }
+
+  // ─── Notify (提测邮件) ─────────────────────────────────────────────────
+  // Mirrors arb deploy-submit Step 3-5:
+  //   3. render a 提测单.md as the email body (not just a self-test embed)
+  //   4. human confirmation (subject + recipients + attachments preview)
+  //   5. send via SMTP, attach only the consolidated reports/test-report.md by default
+  const notifyDisabled = flags.notify === false;
+  const wantsNotify = !notifyDisabled && (flags.notify === true
+    || flags.notify === 'test-report'
+    || flags['notify-dry-run'] === true
+    || isMicro);
+  if (wantsNotify) {
+    const notifyFlags = { ...flags };
+    if (isMicro && flags.notify === undefined && flags['notify-dry-run'] !== true) {
+      notifyFlags.notify = 'test-report';
+      notifyFlags['no-confirm'] = true;
+      notifyFlags.noConfirm = true;
+      state.logEvent(st, 'deliver.micro_test_report_notify', { defaulted: true });
+    }
+    await runNotify({ root, slug, st, base, head, detect, flags: notifyFlags });
+  }
+
+  state.setPhase(st, 'deliver', isMicro ? 'completed' : 'in_progress');
+  helpers.completeWorkflowStep(st, 'deliver');
+  state.logEvent(st, 'deliver', { mode });
+  await state.write(root, slug, st);
+  if (isMicro) {
+    log.dim('next: L0 micro flow ends after deliver; archive is skipped.');
+  } else {
+    log.dim('next: after MR is merged / change is live, run "devflow archive"');
+    log.dim('      archive will merge specs, deposit workspace knowledge, and sync or submit KB changes when configured.');
+  }
+}
+
+async function blockOpenRiskSignals(root, slug, st, flags) {
+  const open = state.openRiskSignals(st);
+  if (!open.length) return false;
+  if (!flags.force) {
+    log.error(`deliver blocked: open risk signals: ${open.map((r) => r.type).join(', ')}`);
+    log.dim('resolve them with verification evidence, or override (audited): devflow deliver --force --reason="..."');
+    process.exitCode = 1;
+    return true;
+  }
+  const reason = flags.reason;
+  if (!reason || reason === true) {
+    log.error('deliver --force requires --reason="..." when accepting open risk signals');
+    process.exitCode = 2;
+    return true;
+  }
+  for (const r of open) {
+    state.acceptRiskSignal(st, r.type, { reason, evidence: ['deliver force acceptance'] });
+  }
+  state.logEvent(st, 'deliver.force_accept_risk_signals', {
+    riskSignals: open.map((r) => r.type),
+    reason,
+  });
+  await state.write(root, slug, st);
+  log.warn(`deliver: force-accepted open risk signals — ${open.map((r) => r.type).join(', ')}`);
+  return false;
+}
+
+async function blockPendingRiskCheckpoint(root, slug, st, flags) {
+  const pending = checkpoint.latestPendingByTypes(st, [
+    'review_fix',
+    'review_blocked',
+    'verification_evidence',
+    'risk_acceptance',
+  ]);
+  if (!pending) return false;
+  if (!flags.force) {
+    log.error(`deliver blocked: pending ${pending.type} checkpoint.`);
+    log.raw('');
+    log.raw(checkpoint.renderNextStepCard(pending));
+    log.dim('override (audited): devflow deliver --force --reason="..."');
+    process.exitCode = 1;
+    return true;
+  }
+  const reason = flags.reason;
+  if (!reason || reason === true) {
+    log.error('deliver --force requires --reason="..." when bypassing pending checkpoints');
+    process.exitCode = 2;
+    return true;
+  }
+  state.logEvent(st, 'deliver.force_bypass_checkpoint', {
+    checkpoint: pending.id,
+    type: pending.type,
+    reason,
+  });
+  await state.write(root, slug, st);
+  log.warn(`deliver: force-bypassed pending ${pending.type} checkpoint`);
+  return false;
+}
+
+async function runNotify({ root, slug, st, base, head, detect, flags }) {
+  // 1) 提测单.md → reports/submit.md; 测试报告 → reports/test-report.md
+  // Overwrite each call so subject/info/test evidence are fresh.
+  const env = flags.env || flags.environment || 'test';
+  const project = flags.project || (detect && detect.remote && detect.remote.project) || '';
+  const build = flags.build || flags.buildNumber || '';
+  const reportsDir = await change.ensureSubdir(root, slug, 'reports');
+  const submitMd = await submit.renderSubmitDoc({
+    root, slug, st, env, base, head, build, detect,
+  });
+  const submitPath = path.join(reportsDir, 'submit.md');
+  await fs.writeFile(submitPath, submitMd, 'utf8');
+  log.ok(`submit doc: devflow/changes/${slug}/reports/submit.md`);
+
+  const testReportMd = await submit.renderTestReportDoc({
+    root, slug, st, env, detect,
+  });
+  const testReportPath = path.join(reportsDir, 'test-report.md');
+  await fs.writeFile(testReportPath, testReportMd, 'utf8');
+  log.ok(`test report: devflow/changes/${slug}/reports/test-report.md`);
+
+  // 2) Subject + attachments
+  const subject = flags.subject
+    || submit.composeSubject({ st, project, env });
+
+  const attachDefault = flags['no-attach-default'] !== true;
+  const attachDocs = flags['attach-docs'] === true || flags.attachDocs === true;
+  const attachDesignPlan = flags['attach-design-plan'] === true || flags.attachDesignPlan === true;
+  const attachReports = flags['attach-reports'] === true || flags.attachReports === true;
+  const attachSubmit = flags['attach-submit'] === true || flags.attachSubmit === true;
+  const extraAttach = flags.attach
+    ? (Array.isArray(flags.attach) ? flags.attach : [flags.attach])
+    : [];
+  const attachments = await submit.collectAttachments({
+    root, slug,
+    includeSubmit:     attachSubmit,
+    includeTestReport: attachDefault,
+    includeDocs:       attachDocs,
+    includeDesignPlan: attachDesignPlan,
+    includeReports:    attachReports,
+    extra: extraAttach,
+  });
+
+  let notify;
+  try { notify = await providers.load(root, { type: 'notify' }); }
+  catch (e) {
+    log.warn(`notify failed (non-fatal): ${e.message}`);
+    return;
+  }
+  if (!notify || notify.driver === 'local') {
+    log.dim('notify: no non-local notify provider configured; skipping');
+    return;
+  }
+
+  // 3) Recipients. Command-line flags override provider defaults configured
+  // through `devflow provider setup` (`config.defaults.to` / `cc`).
+  const { to, cc, source } = resolveNotifyRecipients(flags, notify);
+  if (source === 'provider-defaults') {
+    log.dim('notify recipients: using notify provider defaults');
+  }
+
+  const dryRun = flags['notify-dry-run'] === true;
+  // 4) 人工确认 (arb Step 4) — default ON, --no-confirm to skip, non-TTY refuses by default
+  const wantConfirm = flags.confirm !== false && flags['no-confirm'] !== true;
+  if (wantConfirm) {
+    const ok = await submit.confirmSend({
+      subject,
+      to, cc,
+      attachments,
+      body: submitMd,
+    });
+    if (!ok.ok) {
+      log.error(`notify aborted: ${ok.reason}`);
+      state.logEvent(st, 'deliver.notify_aborted', { reason: ok.reason });
+      process.exitCode = 1;
+      return;
+    }
+  }
+
+  if (to.length === 0) {
+    log.error('notify: --notify-to=<email,...> required');
+    process.exitCode = 2;
+    return;
+  }
+
+  try {
+    const res = await notify.send({
+      subject,
+      body_md: submitMd,
+      to, cc,
+      attachments,
+      dryRun,
+    });
+    const outcome = describeNotifyOutcome({ res, notify, dryRun });
+    log.ok(outcome.message);
+    if (outcome.warning) log.warn(outcome.warning);
+    state.logEvent(st, 'deliver.notify', {
+      to: res.accepted, id: res.id,
+      subject, env, attachments: attachments.map((a) => path.basename(a)),
+      dryRun,
+      status: outcome.status,
+      response: res.response,
+    });
+  } catch (e) {
+    log.warn(`notify failed (non-fatal): ${e.message}`);
+  }
+}
+
+function parseAddrList(v) {
+  if (!v) return [];
+  if (Array.isArray(v)) return v.flatMap((x) => parseAddrList(x));
+  return String(v).split(/[,;]/).map((s) => s.trim()).filter(Boolean);
+}
+
+function resolveNotifyRecipients(flags = {}, notify = {}) {
+  const config = notify.config || {};
+  const defaults = config.defaults || {};
+  const hasToFlag = flags['notify-to'] !== undefined || flags.to !== undefined;
+  const hasCcFlag = flags['notify-cc'] !== undefined || flags.cc !== undefined;
+  const to = hasToFlag
+    ? parseAddrList(flags['notify-to'] || flags.to)
+    : parseAddrList(defaults.to || config.defaultTo);
+  const cc = hasCcFlag
+    ? parseAddrList(flags['notify-cc'] || flags.cc)
+    : parseAddrList(defaults.cc || config.defaultCc);
+  return {
+    to,
+    cc,
+    source: hasToFlag || hasCcFlag ? 'flags' : 'provider-defaults',
+  };
+}
+
+function describeNotifyOutcome({ res = {}, notify = {}, dryRun = false }) {
+  const accepted = (res.accepted || []).join(', ');
+  if (dryRun) {
+    return {
+      status: 'dry_run',
+      message: `notify dry-run composed: ${accepted}`,
+    };
+  }
+
+  const config = notify.config || {};
+  const host = String(config.host || '').toLowerCase();
+  const port = Number(config.port || 0);
+  const localHost = host === 'localhost' || host === '127.0.0.1' || host === '::1';
+  const localMta = localHost || (port === 25 && !config.user);
+  if (localMta) {
+    return {
+      status: 'queued_by_local_mta',
+      message: `notify queued by local SMTP/MTA: ${accepted}`,
+      warning: 'local SMTP/sendmail/postfix accepting a message only means it entered the local mail queue; check queue/provider logs to confirm remote delivery.',
+    };
+  }
+
+  return {
+    status: 'accepted_by_smtp',
+    message: `notify accepted by SMTP server: ${accepted}`,
+  };
+}
+
+module.exports = {
+  run,
+  runNotify,
+  _internals: { parseAddrList, resolveNotifyRecipients, describeNotifyOutcome },
+};