@chenguangyao/devflow-kit 0.1.43

package/src/cli/commands/apply.js

@@ -0,0 +1,198 @@
+'use strict';
+const path = require('path');
+const log = require('../../utils/log.js');
+const state = require('../../core/state.js');
+const checkpoint = require('../../core/checkpoint.js');
+const wt = require('../../core/worktree.js');
+const planTasks = require('../../core/plan-tasks.js');
+const helpers = require('./_helpers.js');
+
+/**
+ * devflow apply [--task=N] [--note="..."] [--no-worktree] [--start|--done|--skip|--fail]
+ *
+ * Behavior:
+ *   - Marks state.phases.apply.status = in_progress
+ *   - state.iterations.apply ++ (counts how many "apply" calls in this change's life)
+ *   - With --task=N:
+ *       - Ensures a worktree exists (.devflow-worktrees/<slug>/task-N) — auto-create unless --no-worktree
+ *       - Records/updates a task entry in state.phases.apply.tasks[]
+ *       - Status transitions: --start | --done | --skip | --fail (default: in_progress)
+ *       - --note appended to that task's notes[]
+ *   - Without --task: just bumps iteration & writes a free-form note (legacy behavior)
+ *
+ * devflow apply does not write code itself — it tracks discipline + state.
+ */
+
+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, 'apply', 'apply')) return;
+
+  const pendingPlanReview = checkpoint.latestPendingByType(st, 'plan_review');
+  if (pendingPlanReview && !flags.force) {
+    log.error('apply blocked: pending plan_review checkpoint.');
+    log.raw('');
+    log.raw(checkpoint.renderNextStepCard(pendingPlanReview));
+    log.raw('');
+    log.dim('override (audited): devflow apply --force --reason="..."');
+    process.exitCode = 1;
+    return;
+  }
+  if (pendingPlanReview && flags.force) {
+    if (!flags.reason) {
+      log.error('--force requires --reason="..." when bypassing plan_review checkpoint');
+      process.exitCode = 2;
+      return;
+    }
+    state.logEvent(st, 'apply.force_bypass_plan_review', { checkpointId: pendingPlanReview.id, reason: flags.reason });
+  }
+
+  const pendingReviewFix = checkpoint.latestPendingByType(st, 'review_fix');
+  if (pendingReviewFix) {
+    checkpoint.resolveCheckpoint(st, pendingReviewFix.id, 'fix');
+    state.logEvent(st, 'checkpoint.resolve', { id: pendingReviewFix.id, decision: 'fix' });
+    state.logEvent(st, 'apply.accept_review_fix', { checkpointId: pendingReviewFix.id });
+  }
+
+  state.setPhase(st, 'plan', 'completed');
+  state.setPhase(st, 'apply', 'in_progress');
+  st.iterations = st.iterations || {}; st.iterations.apply = (st.iterations.apply || 0) + 1;
+
+  const taskRaw = flags.task;
+  const taskId = taskRaw !== undefined ? wt.normaliseTaskId(taskRaw) : null;
+  const note = flags.note;
+  const transition = pickTransition(flags);
+  const noWorktree = flags['no-worktree'] === true || flags.noWorktree === true || flags.worktree === false;
+
+  state.logEvent(st, 'apply', { task: taskId, transition, note });
+
+  let summary;
+  if (taskId) {
+    const apply = wt.ensureTaskBucket(st);
+    let task = apply.tasks.find((t) => t.id === taskId);
+
+    // Auto-create worktree if missing
+    if (!task && !noWorktree) {
+      try {
+        await state.write(root, slug, st);
+        const r = await wt.create(root, slug, { task: taskRaw, title: flags.title });
+        const re = await state.read(root, slug);
+        Object.assign(st, re);
+        task = wt.findTask(st, taskId);
+        if (r.created) log.ok(`auto-created worktree: ${path.relative(root, r.path)}  branch=${r.branch}`);
+      } catch (e) {
+        log.warn(`worktree auto-create failed: ${e.message}`);
+        log.dim('continue tracking task without worktree (use --no-worktree to silence)');
+        task = ensureTaskRecord(st, taskId, { title: flags.title });
+      }
+    } else if (!task) {
+      task = ensureTaskRecord(st, taskId, { title: flags.title });
+    }
+
+    applyTransition(task, transition);
+    if (flags.title) task.title = flags.title;
+    if (note) {
+      task.notes = task.notes || [];
+      task.notes.push({ ts: new Date().toISOString(), text: note });
+    }
+    task.updated_at = new Date().toISOString();
+    summary = `task=${task.id}  status=${task.status}  iterations=${st.iterations.apply}`;
+    if (task.worktree) summary += `\n          worktree: ${path.relative(root, task.worktree)}`;
+    if (task.branch)   summary += `\n          branch:   ${task.branch}`;
+  } else {
+    if (note) {
+      st.phases.apply.notes = st.phases.apply.notes || [];
+      st.phases.apply.notes.push({ ts: new Date().toISOString(), text: note });
+    }
+    summary = `iterations=${st.iterations.apply}`;
+  }
+
+  reconcileApplyStatus(root, slug, st);
+  if (st.phases.apply && st.phases.apply.status === 'completed') {
+    helpers.completeWorkflowStep(st, 'apply');
+  }
+
+  await state.write(root, slug, st);
+  log.ok(`apply: ${summary}`);
+  log.dim(`next: keep coding (TDD!) or run "devflow review --slug=${slug} --round" when ready.`);
+}
+
+function pickTransition(flags) {
+  if (flags.start === true) return 'start';
+  if (flags.done === true)  return 'done';
+  if (flags.skip === true)  return 'skip';
+  if (flags.fail === true)  return 'fail';
+  return null;
+}
+
+function applyTransition(task, t) {
+  const now = new Date().toISOString();
+  switch (t) {
+    case 'start':
+      task.status = 'in_progress';
+      if (!task.started_at) task.started_at = now;
+      break;
+    case 'done':
+      task.status = 'done';
+      task.ended_at = now;
+      break;
+    case 'skip':
+      task.status = 'skipped';
+      task.ended_at = now;
+      break;
+    case 'fail':
+      task.status = 'failed';
+      task.ended_at = now;
+      break;
+    default:
+      if (!task.status || task.status === 'pending') {
+        task.status = 'in_progress';
+        if (!task.started_at) task.started_at = now;
+      }
+  }
+}
+
+function ensureTaskRecord(st, taskId, fields) {
+  const apply = wt.ensureTaskBucket(st);
+  let task = apply.tasks.find((t) => t.id === taskId);
+  if (!task) {
+    task = {
+      id: taskId,
+      title: (fields && fields.title) || taskId,
+      status: 'pending',
+      notes: [],
+      started_at: new Date().toISOString(),
+    };
+    apply.tasks.push(task);
+  }
+  return task;
+}
+
+function reconcileApplyStatus(root, slug, st) {
+  const apply = wt.ensureTaskBucket(st);
+  const planIds = planTasks.readPlanTaskIds(root, slug);
+  const doneStates = new Set(['done', 'skipped']);
+  const statusById = new Map(apply.tasks.map((t) => [t.id, t.status]));
+
+  if (planIds.length > 0) {
+    const completed = planIds.filter((id) => doneStates.has(statusById.get(id)));
+    const remaining = planIds.filter((id) => !doneStates.has(statusById.get(id)));
+    apply.totalTasks = planIds.length;
+    apply.completedTasks = completed;
+    apply.currentTask = remaining[0] || null;
+    apply.status = remaining.length === 0 ? 'completed' : 'in_progress';
+    return apply;
+  }
+
+  apply.completedTasks = apply.tasks.filter((t) => doneStates.has(t.status)).map((t) => t.id);
+  apply.currentTask = (apply.tasks.find((t) => !doneStates.has(t.status)) || {}).id || null;
+  if (apply.tasks.length > 0 && apply.tasks.every((t) => doneStates.has(t.status))) {
+    apply.status = 'completed';
+  }
+  return apply;
+}
+
+module.exports = { run, reconcileApplyStatus };

package/src/cli/commands/archive.js

@@ -0,0 +1,180 @@
+'use strict';
+const fs = require('fs/promises');
+const fsSync = require('fs');
+const path = require('path');
+const readline = require('readline');
+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 delta = require('../../core/delta.js');
+const helpers = require('./_helpers.js');
+const depositMod = require('../../knowledge/deposit.js');
+const syncMod = require('../../knowledge/sync.js');
+const loader = require('../../providers/loader.js');
+
+/** Prompt user to choose external KB push mode. Returns 'mr' | 'push' | 'skip'. */
+async function askKbPushMode(slug) {
+  // Non-interactive environments (CI, piped stdin) → skip
+  if (!process.stdin.isTTY || process.env.CI) return 'skip';
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    log.raw('');
+    log.raw('┌─────────────────────────────────────────────────────┐');
+    log.raw(`│  知识已沉淀到本地 devflow/knowledge/                 │`);
+    log.raw(`│  检测到外部知识库 (kb-git)，如何同步？               │`);
+    log.raw('│                                                     │');
+    log.raw('│  [1] 创建 MR / PR（需审批，推荐）                   │');
+    log.raw('│  [2] 直接推送到主分支（无需审批，快速）              │');
+    log.raw('│  [3] 跳过，稍后手动处理                             │');
+    log.raw('└─────────────────────────────────────────────────────┘');
+    rl.question('  请选择 [1/2/3，默认 1]：', (ans) => {
+      rl.close();
+      const choice = (ans || '1').trim();
+      if (choice === '2') resolve('push');
+      else if (choice === '3') resolve('skip');
+      else resolve('mr');
+    });
+  });
+}
+
+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 (st.mode === 'micro' || st.level === 'L0') {
+    log.error('archive skipped: L0 micro changes do not enter archive.');
+    log.dim('If there is knowledge to keep, run: devflow knowledge deposit --slug=' + slug);
+    process.exitCode = 1;
+    return;
+  }
+
+  // 1. Merge spec deltas
+  log.info('merging spec deltas...');
+  const { merged, conflicts } = await delta.mergeChangeDeltas(root, slug, { dryRun: flags['dry-run'] });
+  if (conflicts.length) {
+    log.error('spec delta merge has conflicts:');
+    for (const c of conflicts) {
+      log.error(`  ${c.file}: ${c.conflicts.map((x) => `${x.kind}/${x.heading} (${x.reason})`).join(', ')}`);
+    }
+    log.dim('resolve in delta/*.md or pass --force to apply anyway.');
+    if (!flags.force) { process.exitCode = 1; return; }
+  }
+  if (merged.length === 0) {
+    log.warn('no spec delta files found — devflow/specs/ NOT updated.');
+    log.warn('  (hint: agent should have created delta/*.md during devflow design)');
+  }
+  for (const m of merged) log.ok(`spec: ${path.relative(root, m.target)}`);
+
+  if (flags['dry-run']) {
+    log.warn('dry-run: archive folder NOT moved, knowledge deposit skipped.');
+    return;
+  }
+
+  // 2. Auto knowledge deposit (before moving the folder, while change dir still exists)
+  const skipDeposit = !!(flags['skip-deposit'] || flags.skipDeposit);
+  let depositedItems = [];
+  if (!skipDeposit) {
+    log.info('knowledge deposit: scanning knowledge/ + design/reports for experience…');
+    try {
+      const plan = await depositMod.deposit(root, { slug, dryRun: true });
+      const actionable = plan.filter((p) => p.action !== 'noop');
+      if (actionable.length > 0) {
+        await depositMod.executeItems(root, actionable, slug);
+        depositedItems = actionable;
+        const created = actionable.filter((p) => p.action === 'create').length;
+        const updated = actionable.filter((p) => p.action === 'update').length;
+        for (const p of actionable) {
+          log.dim(`  ${p.action === 'create' ? 'A' : 'M'} ${p.domain}/${p.category}/${p.filename}`);
+        }
+        log.ok(`knowledge: create=${created} update=${updated} → workspace knowledge/`);
+
+        // 2b. Sync to external KB provider (git or weknora)
+        const depositMode = flags['deposit-mode'] || flags.depositMode;
+        let kbProvider = null;
+        let kbDriver = null;
+        try {
+          const p = await loader.load(root, { type: 'kb' });
+          if (p) { kbProvider = p; kbDriver = p.driver; }
+        } catch { /* no kb provider configured */ }
+
+        if (kbProvider && kbDriver === 'git') {
+          // ── Git-backed KB: ask MR vs direct push ──────────────────────────
+          let mode = depositMode;
+          if (!mode) mode = await askKbPushMode(slug);
+
+          if (mode === 'mr') {
+            log.info('知识库：创建 MR / PR 中…');
+            try {
+              const result = await kbProvider.depositAndCreateMr(root, { items: actionable, slug });
+              if (result.url) log.ok(`知识库 MR 已创建：${result.url}`);
+              else if (result.status === 'pushed_no_mr') log.warn(`已推送分支 ${result.branch}，MR 创建失败：${result.error}`);
+              else if (result.status === 'no_changes') log.dim('知识库：无变更（外部仓库已是最新）');
+            } catch (e) {
+              log.warn(`知识库 MR 创建失败：${e.message}`);
+            }
+          } else if (mode === 'push') {
+            log.info('知识库：直接推送中…');
+            try {
+              const result = await kbProvider.depositAndPush(root, { items: actionable, slug });
+              if (result.status === 'pushed') log.ok(`知识库：已直接推送到 ${result.branch}（${result.commit_hash?.slice(0, 7)}）`);
+              else if (result.status === 'no_changes') log.dim('知识库：无变更');
+            } catch (e) {
+              log.warn(`知识库推送失败：${e.message}`);
+            }
+          } else {
+            log.dim('知识库：已跳过外部同步。稍后可运行 `devflow knowledge deposit --mr` 或 `--push`');
+          }
+        } else if (kbProvider) {
+          // ── WeKnora / other API-based KB: auto sync immediately ───────────
+          log.info('知识库：同步到远端 KB 中…');
+          try {
+            const { summary } = await syncMod.sync(root, { dryRun: false });
+            log.ok(`知识库同步完成：create=${summary.create} update=${summary.update} delete=${summary.delete} noop=${summary.noop}`);
+          } catch (e) {
+            log.warn(`知识库同步失败：${e.message}`);
+            log.dim('  稍后可手动运行 `devflow knowledge sync` 重试');
+          }
+        }
+      } else {
+        log.dim('knowledge: nothing new to deposit (no knowledge/ files, design sections, or incident reports?)');
+      }
+    } catch (err) {
+      log.warn(`knowledge deposit skipped: ${err.message}`);
+    }
+  }
+
+  // 3. Drop legacy duplicate learnings.md before archiving.
+  // Knowledge entries live under knowledge/ now; keeping both creates drift.
+  const src = change.resolveChangeDir(root, slug);
+  const legacyLearnings = path.join(src, 'learnings.md');
+  if (fsSync.existsSync(legacyLearnings)) {
+    await fs.rm(legacyLearnings, { force: true });
+    log.dim('removed legacy learnings.md (knowledge/ is the source of truth)');
+  }
+
+  // 4. Move change folder to archive/
+  const dateStr = new Date().toISOString().slice(0, 10);
+  const targetName = `${dateStr}-${slug}`;
+  const dst = path.join(paths.archiveDir(root), targetName);
+  await fs.mkdir(paths.archiveDir(root), { recursive: true });
+  await fs.rename(src, dst);
+  log.ok(`archive: devflow/archive/${targetName}/`);
+
+  // 5. Final state log (write into archived folder)
+  const stateFile = path.join(dst, 'state.json');
+  if (fsSync.existsSync(stateFile)) {
+    const archived = JSON.parse(await fs.readFile(stateFile, 'utf8'));
+    state.setPhase(archived, 'archive', 'completed');
+    state.logEvent(archived, 'archived');
+    archived.updatedAt = new Date().toISOString();
+    await fs.writeFile(stateFile, JSON.stringify(archived, null, 2) + '\n', 'utf8');
+  }
+
+  log.ok(`workflow complete for ${slug}`);
+}
+
+module.exports = { run };

package/src/cli/commands/checkpoint.js

@@ -0,0 +1,113 @@
+'use strict';
+const fsSync = require('fs');
+const log = require('../../utils/log.js');
+const paths = require('../../core/paths.js');
+const change = require('../../core/change.js');
+const stateMod = require('../../core/state.js');
+const checkpointMod = require('../../core/checkpoint.js');
+
+async function run({ positional = [], flags = {}, cwd }) {
+  const root = cwd || process.cwd();
+  if (!fsSync.existsSync(paths.devflowDir(root))) {
+    log.warn('not a devflow project. run "devflow init" first.');
+    process.exitCode = 1;
+    return;
+  }
+
+  const action = positional[0] || 'show';
+  const slug = flags.slug || (await change.getCurrent(root));
+  if (!slug) {
+    log.warn('no change found. run "devflow ingest <input>" or "devflow new <slug>".');
+    return;
+  }
+
+  const st = await stateMod.read(root, slug);
+
+  if (action === 'add' || action === 'create') {
+    const cp = checkpointMod.addCheckpoint(st, {
+      type: flags.type,
+      phase: flags.phase || st.currentPhase,
+      summary: flags.summary,
+      question: flags.question,
+      options: checkpointMod.parseOptions(flags.options),
+      defaultOption: flags.default || flags.defaultOption,
+      nextAction: flags.nextAction || flags.command,
+      risks: splitList(flags.risks),
+      evidence: splitList(flags.evidence),
+    });
+    stateMod.logEvent(st, 'checkpoint.add', { id: cp.id, type: cp.type, phase: cp.phase });
+    await stateMod.write(root, slug, st);
+    log.ok(`checkpoint added: ${cp.id}`);
+    log.raw('');
+    log.raw(checkpointMod.renderNextStepCard(cp));
+    return;
+  }
+
+  if (action === 'resolve') {
+    const id = flags.id || positional[1];
+    const cp = checkpointMod.resolveCheckpoint(st, id, flags.decision || flags.option, flags.note);
+    stateMod.logEvent(st, 'checkpoint.resolve', { id: cp.id, decision: cp.decision });
+    await stateMod.write(root, slug, st);
+    log.ok(`checkpoint resolved: ${cp.id}`);
+    return;
+  }
+
+  if (action === 'cancel') {
+    const id = flags.id || positional[1];
+    const cp = checkpointMod.cancelCheckpoint(st, id, flags.reason);
+    stateMod.logEvent(st, 'checkpoint.cancel', { id: cp.id, reason: cp.reason });
+    await stateMod.write(root, slug, st);
+    log.ok(`checkpoint cancelled: ${cp.id}`);
+    return;
+  }
+
+  if (action !== 'show') {
+    log.error(`unknown checkpoint action: ${action}`);
+    process.exitCode = 2;
+    return;
+  }
+
+  const pending = checkpointMod.latestPending(st);
+  if (!pending) {
+    if (flags.json === true) {
+      log.raw(JSON.stringify({ pending: null, confirmationCard: null, nextAction: null }, null, 2));
+      return;
+    }
+    log.ok('no pending checkpoint');
+    return;
+  }
+  if (flags.json === true) {
+    log.raw(JSON.stringify(buildShowResponse(slug, pending), null, 2));
+    return;
+  }
+  log.raw(checkpointMod.renderNextStepCard(pending));
+}
+
+function buildShowResponse(slug, pending) {
+  return {
+    type: 'checkpoint_confirmation_surface',
+    slug,
+    pending,
+    confirmationCard: checkpointMod.buildConfirmationCard(pending, confirmationCardOptions(pending)),
+    nextAction: pending.nextAction || (pending.options && pending.options[0] && pending.options[0].command) || null,
+  };
+}
+
+function confirmationCardOptions(checkpoint) {
+  if (checkpoint.type === 'workflow_policy') {
+    return {
+      type: 'workflow_policy_confirm',
+      title: '确认 workflow 风险',
+      primaryActionId: 'accept-risk',
+    };
+  }
+  return {};
+}
+
+function splitList(value) {
+  if (!value) return [];
+  if (Array.isArray(value)) return value;
+  return String(value).split(';').map((s) => s.trim()).filter(Boolean);
+}
+
+module.exports = { run };