@cr1992/agentkit 1.0.0

package/domains/worktree/worktree-archive.mjs

@@ -0,0 +1,135 @@
+// @ts-check
+
+/**
+ * Domain command factory. Dependencies are injected once by the thin CLI composition root,
+ * keeping this module acyclic and independently reviewable.
+ *
+ * `archive` 只处理"目录已经不存在、分支已经安全"的历史 record：它只追加一条 `archived`
+ * trace event，用来让 doctor/list 停止对已经确认安全的历史 record 重复报警。它与 `reclaim`
+ * 完全不同——不删除分支、不删除目录、不改任何 ref、不 prune，因为它的前置条件已经要求目录
+ * 不存在（不然本来就该走 reclaim），archive 只是把"已经确认过的历史"标记出来，纯粹是 trace
+ * 元数据操作。
+ * @param {Record<string, any>} deps
+ */
+export function createCommands(deps) {
+  const {
+    loadRepositoryProfile,
+    loadRecords,
+    selectRecord,
+    liveGitSnapshot,
+    updateRecord,
+    localBranchExists,
+    resolveBaseRef,
+    isAncestor,
+    assertHistoryOperationIdle,
+    git,
+    gitTry,
+    log,
+    die,
+    flag,
+    rejectUnknownFlags,
+    oneLine,
+  } = deps;
+
+  /**
+   * 三项前置条件全部满足才允许归档：
+   *   1. worktree 目录已经不存在（否则应该走 reclaim，或先确认再手工处理）；
+   *   2. 分支已经不存在，或分支 tip 可达于登记的 base ref / 当前 remote HEAD；
+   *   3.（由调用方在此之前检查）worktree 不处于 ready_for_review 的武装监听状态。
+   * 任一条件不满足都返回 `{ ok:false, reason }`，由调用方按 KEEP 惯例处理——不 throw、不
+   * exit，保持和 reclaim 的 KEEP 语义一致。
+   * @param {ReturnType<typeof loadRepositoryProfile>} loaded
+   * @param {Record<string,any>} record
+   */
+  function evaluateArchivePreconditions(loaded, record) {
+    const snapshot = liveGitSnapshot(record);
+    if (snapshot.present) {
+      return {
+        ok: false,
+        reason: 'worktree 目录仍然存在；archive 只接受目录已经不存在的历史 record（目录还在时请走 reclaim，或先确认后再手工清理）。',
+      };
+    }
+    const branchExists = localBranchExists(loaded, record);
+    if (!branchExists) {
+      return { ok: true, basis: 'branch_absent', branchTipSha: record.last_head ?? null, matchedRef: null };
+    }
+    const branchTipSha = git(['rev-parse', `refs/heads/${record.branch}`], loaded.context.current_worktree);
+    const candidateRefs = [];
+    if (record.base_ref) candidateRefs.push(record.base_ref);
+    const remoteHead = resolveBaseRef(loaded.context.current_worktree, loaded.profile.default_base ?? null, null);
+    if (remoteHead?.ref && !candidateRefs.includes(remoteHead.ref)) candidateRefs.push(remoteHead.ref);
+    for (const ref of candidateRefs) {
+      const resolved = gitTry(['rev-parse', '--verify', '--quiet', `${ref}^{commit}`], loaded.context.current_worktree);
+      if (resolved.ok && isAncestor(loaded.context.current_worktree, branchTipSha, resolved.out)) {
+        return { ok: true, basis: 'branch_merged', branchTipSha, matchedRef: ref };
+      }
+    }
+    return {
+      ok: false,
+      reason: candidateRefs.length > 0
+        ? `分支 ${record.branch} 仍然存在，且未合入已知 base（${candidateRefs.join(', ')}）；请先确认已合入或删除分支后再归档。`
+        : `分支 ${record.branch} 仍然存在，且没有可用于判断合入状态的 base ref；请先补登记 base 或删除分支后再归档。`,
+    };
+  }
+
+  function cmdArchive(args) {
+    rejectUnknownFlags(args.flags, ['reason', 'id', 'config']);
+    const reasonInput = flag(args.flags, 'reason');
+    if (!reasonInput) die('archive 需要 --reason "<text>"。', 2);
+    const reason = oneLine(reasonInput, '--reason', 500);
+    const loaded = loadRepositoryProfile({ explicitConfigPath: flag(args.flags, 'config') });
+    const records = loadRecords(loaded.context.common_dir);
+    const record = selectRecord(records, args.positionals[0] ?? null, flag(args.flags, 'id'));
+
+    if (record.worktree_state === 'archived') {
+      log(`KEEP ${record.path}: record 已经归档，拒绝重复归档。`);
+      process.exitCode = 1;
+      return;
+    }
+    if (record.worktree_state === 'reclaimed') {
+      log(`KEEP ${record.path}: record 已经 reclaimed，无需归档。`);
+      process.exitCode = 1;
+      return;
+    }
+    if (record.worktree_state === 'reclaim_ready') {
+      log(`KEEP ${record.path}: reclaim 流程被中断（reclaim_ready）；请先修复并完成 reclaim，不能用 archive 绕过。`);
+      process.exitCode = 1;
+      return;
+    }
+    assertHistoryOperationIdle(record, 'archive');
+
+    const activeWatch = record.auto_reclaim && !['disarmed', 'reclaimed'].includes(record.auto_reclaim.state)
+      ? record.auto_reclaim
+      : null;
+    if (activeWatch) {
+      log(`KEEP ${record.path}: worktree 仍处于 ready_for_review 武装监听状态（state=${activeWatch.state}）；请先 unwatch ${record.task} 再归档。`);
+      process.exitCode = 1;
+      return;
+    }
+
+    const evaluation = evaluateArchivePreconditions(loaded, record);
+    if (!evaluation.ok) {
+      log(`KEEP ${record.path}: ${evaluation.reason}`);
+      process.exitCode = 1;
+      return;
+    }
+
+    const now = new Date().toISOString();
+    const details = {
+      reason,
+      basis: evaluation.basis,
+      branch: record.branch ?? null,
+      branch_tip_sha: evaluation.branchTipSha,
+      matched_base_ref: evaluation.matchedRef,
+    };
+    const updated = updateRecord(record, 'archived', (next) => {
+      next.worktree_state = 'archived';
+      next.archived_at = now;
+      next.archive = { ...details };
+    }, details, loaded.context.common_dir);
+
+    log(`已归档 ${updated.worktree_id.slice(0, 8)} task=${updated.task}（basis=${evaluation.basis}${evaluation.matchedRef ? `, base=${evaluation.matchedRef}` : ''}）；不删除分支、不删除目录、不改 refs。`);
+  }
+
+  return { cmdArchive };
+}

package/domains/worktree/worktree-artifact.mjs

@@ -0,0 +1,123 @@
+// @ts-check
+
+/**
+ * Domain command factory. Dependencies are injected once by the thin CLI composition root,
+ * keeping this module acyclic and independently reviewable.
+ * @param {Record<string, any>} deps
+ */
+export function createCommands(deps) {
+  const {
+    resolve,
+    ensureRepositoryIdentity,
+    loadRepositoryProfile,
+    readRepositoryIdentity,
+    git,
+    gitTry,
+    die,
+    flag,
+    readJsonFileOrDie,
+    rejectUnknownFlags,
+    loadRecords,
+    selectRecord,
+    liveGitSnapshot,
+    assertHistoryOperationIdle,
+  } = deps;
+
+  function worktreeEnvelopeContext(args) {
+    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 identity = ensureRepositoryIdentity(loaded.context);
+    const snapshot = liveGitSnapshot(record);
+    return { loaded, record, identity, snapshot };
+  }
+
+  function buildBinding(record, identity, snapshot) {
+    return {
+      schema_version: 1,
+      provider: 'manage-worktrees',
+      repository_id: identity.repository_id,
+      worktree_id: record.worktree_id,
+      workdir: record.path,
+      branch: record.branch,
+      owner: { agent: record.agent.host, agent_id: record.agent.id, epoch: record.ownership_epochs?.length ?? 0 },
+      base_sha: record.base_sha,
+      head_sha: snapshot.head ?? record.last_head,
+      task_status: record.task_status,
+      worktree_state: record.worktree_state,
+    };
+  }
+
+  function buildArtifact(record, identity, snapshot, cwd) {
+    if (!snapshot.present) die('Artifact 要求 worktree 当前存在。', 2);
+    if (snapshot.dirty !== false) die('Artifact 要求 worktree clean。', 2);
+    if (!snapshot.head) die('Artifact 无法冻结 HEAD。', 2);
+    const objectFormat = git(['rev-parse', '--show-object-format'], cwd);
+    return {
+      schema_version: 1,
+      provider: 'manage-worktrees',
+      repository_id: identity.repository_id,
+      object_format: objectFormat,
+      base_sha: record.base_sha,
+      artifact_sha: snapshot.head,
+      branch_hint: record.branch ?? undefined,
+      worktree_id: record.worktree_id,
+      ownership_epoch: record.ownership_epochs?.length ?? 0,
+    };
+  }
+
+  function cmdBinding(args) {
+    rejectUnknownFlags(args.flags, ['json', 'id', 'config']);
+    const { record, identity, snapshot } = worktreeEnvelopeContext(args);
+    console.log(JSON.stringify(buildBinding(record, identity, snapshot), null, 2));
+  }
+
+  function cmdArtifact(args) {
+    rejectUnknownFlags(args.flags, ['json', 'id', 'config']);
+    const { loaded, record, identity, snapshot } = worktreeEnvelopeContext(args);
+    assertHistoryOperationIdle(record, 'artifact');
+    console.log(JSON.stringify(buildArtifact(record, identity, snapshot, loaded.context.current_worktree), null, 2));
+  }
+
+  function verifyArtifactEnvelope(artifact, loaded, records = loadRecords(loaded.context.common_dir)) {
+    if (!artifact || artifact.schema_version !== 1 || artifact.provider !== 'manage-worktrees') throw new Error('Artifact schema/provider 无效');
+    if (typeof artifact.worktree_id !== 'string' || !artifact.worktree_id) throw new Error('Artifact worktree_id 缺失');
+    if (!Number.isInteger(artifact.ownership_epoch) || artifact.ownership_epoch < 1) throw new Error('Artifact ownership_epoch 缺失或无效');
+    const identity = readRepositoryIdentity(loaded.context);
+    if (!identity || artifact.repository_id !== identity.repository_id) throw new Error('Artifact repository_id 不匹配');
+    const objectFormat = git(['rev-parse', '--show-object-format'], loaded.context.current_worktree);
+    if (artifact.object_format !== objectFormat) throw new Error('Artifact object_format 不匹配');
+    const length = objectFormat === 'sha256' ? 64 : objectFormat === 'sha1' ? 40 : 0;
+    for (const field of ['base_sha', 'artifact_sha']) {
+      if (!new RegExp(`^[0-9a-f]{${length}}$`, 'u').test(String(artifact[field] ?? ''))) throw new Error(`${field} 不是完整 object id`);
+      if (!gitTry(['cat-file', '-e', `${artifact[field]}^{commit}`], loaded.context.current_worktree).ok) throw new Error(`${field} 不是可达 commit`);
+    }
+    if (!gitTry(['merge-base', '--is-ancestor', artifact.base_sha, artifact.artifact_sha], loaded.context.current_worktree).ok) throw new Error('Artifact base 不是 artifact ancestor');
+    const record = records.find((candidate) => candidate.worktree_id === artifact.worktree_id);
+    if (!record) throw new Error('Artifact worktree_id 不存在');
+    if (record.base_sha !== artifact.base_sha) throw new Error('Artifact base_sha 与 worktree record 不匹配');
+    if (artifact.ownership_epoch !== (record.ownership_epochs?.length ?? 0)) throw new Error('Artifact ownership_epoch 已 stale');
+    const live = liveGitSnapshot(record);
+    if (!live.present) throw new Error('Artifact worktree 已不存在');
+    if (live.head !== artifact.artifact_sha) throw new Error('Artifact SHA 与 live HEAD 不一致');
+    if (live.dirty !== false) throw new Error('Artifact worktree 已变脏');
+    return { valid: true, repository_id: artifact.repository_id, artifact_sha: artifact.artifact_sha, object_format: artifact.object_format };
+  }
+
+  function cmdVerifyArtifact(args) {
+    rejectUnknownFlags(args.flags, ['json', 'config']);
+    const path = args.positionals[0];
+    if (!path) die('verify-artifact 需要 Artifact JSON 文件。', 2);
+    const loaded = loadRepositoryProfile({ explicitConfigPath: flag(args.flags, 'config') });
+    const artifact = readJsonFileOrDie(resolve(path), 'Artifact 文件');
+    console.log(JSON.stringify(verifyArtifactEnvelope(artifact, loaded), null, 2));
+  }
+
+
+  return {
+    worktreeEnvelopeContext,
+    verifyArtifactEnvelope,
+    cmdBinding,
+    cmdArtifact,
+    cmdVerifyArtifact,
+  };
+}