@cr1992/agentkit 1.0.0

package/domains/worktree/worktree-batch-plan.mjs

@@ -0,0 +1,198 @@
+// @ts-check
+
+/**
+ * @param {Record<string, any>} deps
+ */
+export function createCommands(deps) {
+  const {
+    createHash,
+    computeConflictScan,
+    printConflictScan,
+    loadRepositoryProfile,
+    readRepositoryIdentity,
+    resolveBaseRef,
+    gitTry,
+    isAncestor,
+    log,
+    die,
+    flag,
+    rejectUnknownFlags,
+    loadRecords,
+    selectRecord,
+    liveGitSnapshot,
+    canonicalJson,
+    gitOperationState,
+  } = deps;
+
+  /** @param {string} targetSha @param {string[]} orderedInputShas */
+  function batchFingerprint(targetSha, orderedInputShas) {
+    const input = { schema_version: 1, target_sha: targetSha, ordered_input_shas: orderedInputShas };
+    return `sha256:${createHash('sha256').update(JSON.stringify(canonicalJson(input))).digest('hex')}`;
+  }
+
+  /** @param {Record<string,any>} item @param {string} code @param {string} detail */
+  function blockBatchItem(item, code, detail) {
+    item.state = 'blocked';
+    item.reasons.push({ code, detail });
+  }
+
+  /**
+   * 为同一 repository identity 内的多个 feature 生成只读、可复现的集成候选计划。
+   * 不 fetch、不 merge、不创建 worktree；调用者必须把 target SHA 和有序输入 SHA 当作冻结契约。
+   *
+   * 与 cmdPlanBatch 分离是为了让 batch-integrate 能用同一套规则重算计划做新鲜度校验，
+   * 避免「规划口径」和「合成口径」各写一份而悄悄漂移。
+   * @param {ReturnType<typeof loadRepositoryProfile>} loaded
+   * @param {string[]} selectors
+   * @param {string|null} targetOverride
+   */
+  function computeBatchPlan(loaded, selectors, targetOverride) {
+    const records = loadRecords(loaded.context.common_dir);
+    const target = resolveBaseRef(
+      loaded.context.current_worktree,
+      loaded.profile.default_base,
+      targetOverride,
+    );
+    const targetCommit = gitTry(['rev-parse', '--verify', `${target.ref}^{commit}`], loaded.context.current_worktree);
+    if (!targetCommit.ok || !targetCommit.out) die(`无法解析批次 target commit: ${target.ref}`, 2);
+
+    const seenRecords = new Set();
+    const requested = selectors.map((selector) => {
+      const record = selectRecord(records, selector, null);
+      if (seenRecords.has(record.worktree_id)) die(`重复 selector 指向同一 record: ${selector}`, 2);
+      seenRecords.add(record.worktree_id);
+      const snapshot = liveGitSnapshot(record);
+      const item = {
+        selector,
+        worktree_id: record.worktree_id,
+        task: record.task,
+        branch: record.branch ?? null,
+        path: record.path,
+        task_status: record.task_status,
+        worktree_state: record.worktree_state,
+        base_ref: record.base_ref ?? null,
+        base_sha: record.base_sha ?? null,
+        head: snapshot.head ?? null,
+        upstream_ref: snapshot.upstream ?? null,
+        upstream_sha: null,
+        state: 'candidate',
+        reasons: [],
+      };
+
+      if (!snapshot.head) {
+        blockBatchItem(item, 'HEAD_UNREADABLE', '无法读取 feature HEAD。');
+        return item;
+      }
+      if (isAncestor(loaded.context.current_worktree, snapshot.head, targetCommit.out)) {
+        item.state = 'already_integrated';
+        item.reasons.push({ code: 'ALREADY_IN_TARGET', detail: `${snapshot.head} 已被 ${target.ref} 包含。` });
+        return item;
+      }
+      if (!snapshot.present || record.worktree_state === 'reclaimed') {
+        blockBatchItem(item, 'WORKTREE_NOT_PRESENT', '尚未进入 target 的批次输入必须来自仍存在的 tracked worktree。');
+        return item;
+      }
+      if (!['ready_for_review', 'integrating'].includes(record.task_status)) {
+        blockBatchItem(item, 'NOT_READY_FOR_REVIEW', `task_status=${record.task_status}`);
+      }
+      if (snapshot.dirty !== false) {
+        blockBatchItem(item, 'DIRTY_WORKTREE', '批次只接受干净 worktree 的固定提交。');
+      }
+      const operation = gitOperationState(record.path);
+      if (operation) blockBatchItem(item, 'GIT_OPERATION_IN_PROGRESS', `检测到 ${operation}。`);
+      if (record.last_head && record.last_head !== snapshot.head) {
+        blockBatchItem(item, 'HEAD_DRIFT', `trace=${record.last_head} live=${snapshot.head}`);
+      }
+      if (!snapshot.upstream) {
+        blockBatchItem(item, 'UPSTREAM_MISSING', 'feature branch 尚未登记 upstream，无法证明已推送。');
+        return item;
+      }
+      const upstreamCommit = gitTry(['rev-parse', '--verify', `${snapshot.upstream}^{commit}`], record.path);
+      item.upstream_sha = upstreamCommit.ok ? upstreamCommit.out : null;
+      if (!upstreamCommit.ok || upstreamCommit.out !== snapshot.head) {
+        blockBatchItem(
+          item,
+          'UPSTREAM_NOT_AT_HEAD',
+          upstreamCommit.ok ? `upstream=${upstreamCommit.out} live=${snapshot.head}` : `无法解析 ${snapshot.upstream}`,
+        );
+      }
+      return item;
+    });
+
+    const candidates = requested.filter((item) => item.state === 'candidate');
+    for (let index = 0; index < candidates.length; index++) {
+      const item = candidates[index];
+      const duplicate = candidates.slice(0, index).find((other) => other.state === 'candidate' && other.head === item.head);
+      if (duplicate) {
+        item.state = 'covered';
+        item.reasons.push({ code: 'DUPLICATE_HEAD', detail: `与 ${duplicate.task} 指向同一 HEAD。` });
+        continue;
+      }
+      const covering = candidates.find((other) =>
+        other !== item &&
+        other.state === 'candidate' &&
+        other.head !== item.head &&
+        isAncestor(loaded.context.current_worktree, item.head, other.head),
+      );
+      if (covering) {
+        item.state = 'covered';
+        item.reasons.push({ code: 'COVERED_BY_DESCENDANT', detail: `${item.task} 已包含在 ${covering.task}。` });
+      }
+    }
+
+    const included = requested.filter((item) => item.state === 'candidate');
+    const blockers = requested
+      .filter((item) => item.state === 'blocked')
+      .flatMap((item) => item.reasons.map((reason) => ({ task: item.task, worktree_id: item.worktree_id, ...reason })));
+    if (included.length === 0) blockers.push({ task: null, worktree_id: null, code: 'NO_UNIQUE_INPUT', detail: '没有需要合成的唯一 feature HEAD。' });
+    const repositoryId = readRepositoryIdentity(loaded.context)?.repository_id ?? null;
+    const ready = blockers.length === 0;
+    return {
+      schema_version: 1,
+      generated_at: new Date().toISOString(),
+      repository_id: repositoryId,
+      // 原始 selector 全集（含随后被折叠或已在 target 的输入）。重验新鲜度必须按这一份重算：
+      // 只回算 included 会把「被折叠的父分支后来前进了」这类漂移整个漏掉。
+      requested_selectors: [...selectors],
+      target: { ref: target.ref, sha: targetCommit.out, source: target.source },
+      ready,
+      fingerprint: ready ? batchFingerprint(targetCommit.out, included.map((item) => item.head)) : null,
+      included,
+      excluded: requested.filter((item) => item.state !== 'candidate' && item.state !== 'blocked'),
+      blockers,
+    };
+  }
+
+
+  /** @param {{positionals:string[],flags:Map<string,unknown>}} args */
+  function cmdPlanBatch(args) {
+    rejectUnknownFlags(args.flags, ['json', 'target', 'config', 'scan-conflicts']);
+    if (args.positionals.length < 2) die('plan-batch 至少需要两个 feature selector。', 2);
+    const loaded = loadRepositoryProfile({ explicitConfigPath: flag(args.flags, 'config') });
+    const result = computeBatchPlan(loaded, args.positionals, flag(args.flags, 'target'));
+    const included = result.included;
+    const blockers = result.blockers;
+    // 冲突矩阵是 cmdPlanBatch 的**附加输出**，不进 computeBatchPlan：后者同时是 batch-integrate
+    // 的新鲜度重算口径，往里塞扫描结果会让每次合成都白跑一遍 merge-tree，也会把决策辅助信息
+    // 混进"必须逐项比对"的冻结契约里。指纹只绑 SHA，加不加 --scan-conflicts 都不变。
+    if (args.flags.get('scan-conflicts')) {
+      result.conflict_scan = computeConflictScan(loaded.context.current_worktree, result.target, included);
+    }
+    if (args.flags.get('json')) console.log(JSON.stringify(result, null, 2));
+    else {
+      log(`batch target=${result.target.ref}@${result.target.sha.slice(0, 12)} ready=${result.ready} inputs=${included.length}`);
+      for (const item of included) console.log(`  [INCLUDE] ${item.task} ${item.head.slice(0, 12)} upstream=${item.upstream_ref}`);
+      for (const item of result.excluded) console.log(`  [${item.state.toUpperCase()}] ${item.task} ${item.reasons.map((reason) => reason.code).join(',')}`);
+      for (const blocker of blockers) console.log(`  [BLOCK] ${blocker.task ?? '-'} ${blocker.code}: ${blocker.detail}`);
+      if (result.fingerprint) console.log(`  fingerprint=${result.fingerprint}`);
+      if (result.conflict_scan) printConflictScan(result.conflict_scan);
+    }
+    if (!result.ready) process.exitCode = 1;
+  }
+
+  return {
+    batchFingerprint,
+    computeBatchPlan,
+    cmdPlanBatch,
+  };
+}

package/domains/worktree/worktree-batch-result.mjs

@@ -0,0 +1,241 @@
+// @ts-check
+
+/**
+ * @param {Record<string, any>} deps
+ */
+export function createCommands(deps) {
+  const {
+    existsSync,
+    readFileSync,
+    resolve,
+    loadRepositoryProfile,
+    DIGEST_PATTERN,
+    contentDigest,
+    log,
+    die,
+    flag,
+    rejectUnknownFlags,
+    oneLine,
+    loadRecords,
+    selectRecord,
+    liveGitSnapshot,
+    updateRecord,
+    canonicalJson,
+    exactCommitOid,
+    gitOperationState,
+    isAncestor,
+  } = deps;
+
+  function plainObject(value, label) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) die(`${label} 必须是 JSON object。`, 2);
+    return /** @type {Record<string,any>} */ (value);
+  }
+
+  /** @param {Record<string,any>} value @param {string[]} allowed @param {string} label */
+  function rejectUnknownJsonKeys(value, allowed, label) {
+    const allow = new Set(allowed);
+    const unknown = Object.keys(value).filter((key) => !allow.has(key));
+    if (unknown.length) die(`${label} 包含未知字段: ${unknown.join(', ')}。`, 2);
+  }
+
+  /**
+   * 批次证据只冻结可审计摘要，不接收原始日志、环境变量或凭证。
+   * @param {string} path
+   */
+  function readBatchEvidenceFile(path) {
+    if (!existsSync(path)) die(`--evidence 文件不存在: ${path}`, 2);
+    const bytes = readFileSync(path);
+    if (bytes.length > 128 * 1024) die('--evidence 最大 128 KiB；原始日志应放在外部证据存储。', 2);
+    let parsed;
+    try { parsed = JSON.parse(bytes.toString('utf8')); } catch (error) {
+      die(`--evidence 文件不是合法 JSON: ${error instanceof Error ? error.message : String(error)}`, 2);
+    }
+    const root = plainObject(parsed, '--evidence 根节点');
+    rejectUnknownJsonKeys(root, ['schema_version', 'contract_digest', 'checks'], '--evidence');
+    if (root.schema_version !== 1) die('--evidence schema_version 必须是 1。', 2);
+    if (root.contract_digest !== undefined && root.contract_digest !== null && !DIGEST_PATTERN.test(root.contract_digest)) {
+      die('--evidence contract_digest 必须是 sha256 digest 或 null。', 2);
+    }
+    if (!Array.isArray(root.checks) || root.checks.length === 0 || root.checks.length > 100) {
+      die('--evidence checks 必须包含 1-100 项。', 2);
+    }
+    const names = new Set();
+    const checks = root.checks.map((raw, index) => {
+      const check = plainObject(raw, `checks[${index}]`);
+      rejectUnknownJsonKeys(check, ['name', 'environment', 'argv', 'outcome', 'exit_code', 'evidence_refs'], `checks[${index}]`);
+      const name = oneLine(String(check.name ?? ''), `checks[${index}].name`, 120);
+      if (names.has(name)) die(`--evidence check name 重复: ${name}`, 2);
+      names.add(name);
+      const environment = plainObject(check.environment, `checks[${index}].environment`);
+      const environmentEntries = Object.entries(environment);
+      if (environmentEntries.length > 50 || environmentEntries.some(([key, value]) => (
+        !/^[a-z][a-z0-9_.-]{0,63}$/u.test(key) ||
+        /(?:secret|token|password|credential|private[_-]?key|api[_-]?key)/u.test(key) ||
+        !['string', 'number', 'boolean'].includes(typeof value) ||
+        (typeof value === 'number' && !Number.isFinite(value)) ||
+        (typeof value === 'string' && (value.length > 500 || /[\u0000\r\n]/u.test(value)))
+      ))) {
+        die(`checks[${index}].environment 只接受不含敏感键的有界标量元数据。`, 2);
+      }
+      if (!Array.isArray(check.argv) || check.argv.length === 0 || check.argv.length > 100 || check.argv.some((item) => typeof item !== 'string' || !item || item.length > 1000 || /[\u0000\r\n]/u.test(item))) {
+        die(`checks[${index}].argv 必须是 1-100 个安全字符串组成的 argv。`, 2);
+      }
+      if (!['passed', 'failed', 'undecidable'].includes(check.outcome)) {
+        die(`checks[${index}].outcome 只接受 passed / failed / undecidable。`, 2);
+      }
+      if (!Number.isInteger(check.exit_code) || check.exit_code < 0 || check.exit_code > 255) {
+        die(`checks[${index}].exit_code 必须是 0-255 整数。`, 2);
+      }
+      if (check.outcome === 'passed' && check.exit_code !== 0) die(`checks[${index}] passed 时 exit_code 必须为 0。`, 2);
+      if (check.outcome === 'failed' && check.exit_code === 0) die(`checks[${index}] failed 时 exit_code 不能为 0。`, 2);
+      if (!Array.isArray(check.evidence_refs) || check.evidence_refs.length === 0 || check.evidence_refs.length > 20) {
+        die(`checks[${index}].evidence_refs 必须包含 1-20 项。`, 2);
+      }
+      const evidenceRefs = check.evidence_refs.map((rawRef, refIndex) => {
+        const ref = plainObject(rawRef, `checks[${index}].evidence_refs[${refIndex}]`);
+        rejectUnknownJsonKeys(ref, ['kind', 'id', 'digest'], `checks[${index}].evidence_refs[${refIndex}]`);
+        const kind = oneLine(String(ref.kind ?? ''), 'evidence kind', 40);
+        const id = oneLine(String(ref.id ?? ''), 'evidence id', 1000);
+        if (!DIGEST_PATTERN.test(ref.digest ?? '')) die(`checks[${index}].evidence_refs[${refIndex}].digest 必须是 sha256 digest。`, 2);
+        return { kind, id, digest: ref.digest };
+      });
+      return { name, environment: canonicalJson(environment), argv: check.argv, outcome: check.outcome, exit_code: check.exit_code, evidence_refs: evidenceRefs };
+    });
+    const manifest = canonicalJson({ schema_version: 1, contract_digest: root.contract_digest ?? null, checks });
+    return { manifest, digest: contentDigest(Buffer.from(JSON.stringify(manifest))) };
+  }
+
+  /**
+   * 登记 Profile 声明的合成后步骤的执行结果。工具只记录 controller 的回报，从不代跑。
+   * @param {{positionals:string[],flags:Map<string,unknown>}} args
+   */
+  function cmdBatchStep(args) {
+    rejectUnknownFlags(args.flags, ['step', 'state', 'note', 'id', 'json', 'config']);
+    const loaded = loadRepositoryProfile({ explicitConfigPath: flag(args.flags, 'config') });
+    const record = selectRecord(loadRecords(loaded.context.common_dir), args.positionals[0] ?? null, flag(args.flags, 'id'));
+    const stepName = flag(args.flags, 'step');
+    const state = flag(args.flags, 'state');
+    if (!stepName) die('batch-step 需要 --step <name>。', 2);
+    if (!['done', 'skipped', 'failed'].includes(state ?? '')) die('--state 只接受 done / skipped / failed。', 2);
+    const batch = record.batch_integration;
+    if (!batch || batch.state !== 'composed') die(`${record.task} 不是已合成的集成候选，无法登记合成后步骤。`);
+    if (record.batch_result) die('batch_result 已冻结，不能再修改合成后步骤。', 2);
+    const steps = batch.post_integrate_steps ?? [];
+    const target = steps.find((step) => step.name === stepName);
+    if (!target) {
+      die(
+        `未声明的步骤名: ${stepName}；当前候选只登记 Profile 声明过的步骤` +
+        `${steps.length ? `：${steps.map((step) => step.name).join(', ')}` : '（该 Profile 未声明任何步骤）'}。`,
+        2,
+      );
+    }
+    const note = flag(args.flags, 'note') ? oneLine(flag(args.flags, 'note'), 'note', 240) : null;
+    const now = new Date().toISOString();
+    const updated = updateRecord(record, 'batch_post_step_recorded', (next) => {
+      const step = next.batch_integration.post_integrate_steps.find((item) => item.name === stepName);
+      step.state = state;
+      step.note = note;
+      step.recorded_at = now;
+      next.last_seen_at = now;
+    }, { step: stepName, state, note, fingerprint: batch.fingerprint }, loaded.context.common_dir);
+    const recorded = updated.batch_integration.post_integrate_steps;
+    if (args.flags.get('json')) {
+      console.log(JSON.stringify({ schema_version: 1, worktree_id: updated.worktree_id, post_integrate_steps: recorded }, null, 2));
+      return;
+    }
+    log(`已登记 ${stepName} -> ${state}`);
+    const pending = recorded.filter((step) => step.state === 'pending');
+    console.log(pending.length === 0
+      ? '  合成后步骤已全部登记。'
+      : `  仍待登记: ${pending.map((step) => step.name).join(', ')}`);
+  }
+
+  /**
+   * 冻结一次性集成候选的终态验收结果。结果不可覆盖；新 target/input/contract 必须另起候选。
+   * @param {{positionals:string[],flags:Map<string,unknown>}} args
+   */
+  function cmdBatchResult(args) {
+    rejectUnknownFlags(args.flags, ['state', 'candidate', 'evidence', 'reason', 'id', 'json', 'config']);
+    const loaded = loadRepositoryProfile({ explicitConfigPath: flag(args.flags, 'config') });
+    let record = selectRecord(loadRecords(loaded.context.common_dir), args.positionals[0] ?? null, flag(args.flags, 'id'));
+    const outcome = flag(args.flags, 'state');
+    if (!['passed', 'failed', 'stale'].includes(outcome ?? '')) die('--state 只接受 passed / failed / stale。', 2);
+    const candidateInput = flag(args.flags, 'candidate');
+    if (!candidateInput) die('batch-result 需要 --candidate <exact-object-id>。', 2);
+    const candidateSha = exactCommitOid(loaded.context.current_worktree, candidateInput, '--candidate');
+    const evidencePath = flag(args.flags, 'evidence');
+    if (outcome !== 'stale' && !evidencePath) die(`${outcome} 结果需要 --evidence <json>。`, 2);
+    const evidence = evidencePath ? readBatchEvidenceFile(resolve(evidencePath)) : null;
+    const reason = flag(args.flags, 'reason') ? oneLine(flag(args.flags, 'reason'), '--reason', 500) : null;
+    if (outcome === 'stale' && !reason) die('stale 结果需要 --reason <原因>。', 2);
+    if (outcome !== 'stale' && !evidence.manifest.contract_digest) {
+      die(`${outcome} 结果的 Evidence 必须提供非空 contract_digest；合同变化必须另起候选。`, 2);
+    }
+    if (outcome === 'passed' && evidence.manifest.checks.some((check) => check.outcome !== 'passed')) {
+      die('passed 结果要求所有 evidence checks 都为 passed。', 2);
+    }
+    if (outcome === 'failed' && !evidence.manifest.checks.some((check) => check.outcome === 'failed')) {
+      die('failed 结果至少需要一个 failed evidence check。', 2);
+    }
+    const batch = record.batch_integration;
+    if (!batch || batch.state !== 'composed') die(`${record.task} 不是已合成的集成候选。`, 2);
+    if (!['integrating', 'done'].includes(record.task_status)) die(`batch-result 不接受 ${record.task_status} 候选。`, 2);
+    const requested = canonicalJson({
+      schema_version: 1,
+      outcome,
+      candidate_sha: candidateSha,
+      fingerprint: batch.fingerprint,
+      target_ref: batch.target_ref,
+      target_sha: batch.target_sha,
+      ordered_input_shas: (batch.ordered_inputs ?? []).map((item) => item.head),
+      evidence_manifest_digest: evidence?.digest ?? null,
+      evidence_manifest: evidence?.manifest ?? null,
+      reason,
+    });
+    const requestedDigest = contentDigest(Buffer.from(JSON.stringify(requested)));
+    if (record.batch_result) {
+      if (record.batch_result.result_digest !== requestedDigest) die('batch_result 已冻结且与本次输入不同；不得覆盖终态结果。', 2);
+      if (args.flags.get('json')) console.log(JSON.stringify(record.batch_result, null, 2));
+      else log(`批次结果已冻结（幂等） ${record.task} ${outcome} ${candidateSha.slice(0, 12)}`);
+      return;
+    }
+    if (record.worktree_state !== 'present') die(`batch-result 只接受 present 候选；当前 ${record.worktree_state}。`, 2);
+    const live = liveGitSnapshot(record);
+    if (!live.present) die(`候选 worktree missing: ${record.path}`, 2);
+    if (live.dirty !== false) die(`候选 worktree 必须干净：${record.path}`, 2);
+    const operation = gitOperationState(record.path);
+    if (operation) die(`候选仍处于 ${operation} 中间态，拒绝冻结结果。`, 2);
+    if (live.head?.toLowerCase() !== candidateSha) die(`--candidate 与 live HEAD 不一致：expected ${live.head}`, 2);
+    if (!isAncestor(record.path, batch.composed_sha, candidateSha)) {
+      die(`candidate SHA 不是 composed_sha ${batch.composed_sha} 的后继，拒绝冻结。`, 2);
+    }
+    if (outcome === 'passed') {
+      const incomplete = (batch.post_integrate_steps ?? []).filter((step) => !['done', 'skipped'].includes(step.state));
+      if (incomplete.length) die(`passed 前仍有未通过的合成后步骤: ${incomplete.map((step) => `${step.name}=${step.state}`).join(', ')}`, 2);
+    }
+    const recordedAt = new Date().toISOString();
+    record = updateRecord(record, 'batch_result_recorded', (next) => {
+      next.batch_result = { ...requested, result_digest: requestedDigest, recorded_at: recordedAt };
+      next.task_status = 'done';
+      next.last_head = candidateSha;
+      next.last_seen_at = recordedAt;
+    }, {
+      outcome,
+      candidate_sha: candidateSha,
+      fingerprint: batch.fingerprint,
+      result_digest: requestedDigest,
+      evidence_manifest_digest: evidence?.digest ?? null,
+      reason,
+    }, loaded.context.common_dir);
+    if (args.flags.get('json')) console.log(JSON.stringify(record.batch_result, null, 2));
+    else log(`已冻结批次结果 ${record.task} ${outcome} sha=${candidateSha.slice(0, 12)} evidence=${evidence?.digest ?? 'none'}`);
+  }
+
+  /** @param {ReturnType<typeof loadRepositoryProfile>} loaded */
+
+
+  return {
+    cmdBatchStep,
+    cmdBatchResult,
+  };
+}