@longzai-intelligence-git/massive-sync-pipeline 0.0.1

package/dist/index.d.ts

@@ -0,0 +1,149 @@
+import { CommitSha, GitExecutor, OnProgress, RefName } from "@longzai-intelligence-git/core";
+//#region src/pipeline.d.ts
+/**
+ * 同步策略（与 contract 的 MassiveTaskStrategy 同构，但 pipeline 不依赖 contract）
+ */
+type SyncStrategy = 'fast_forward_only' | 'rebase' | 'merge';
+/**
+ * 阶段标识（与 core 的 MassiveStage 同构）
+ */
+type PipelineStage = 'fetch' | 'rebase' | 'merge' | 'push';
+/**
+ * 单阶段结果
+ */
+type StageResult = {
+  stage: PipelineStage;
+  status: 'completed' | 'skipped';
+  durationMs: number;
+  resultingSha: CommitSha | null;
+  error: null;
+};
+/**
+ * 断点续传起点（pipeline 只关心阶段跳过逻辑，不关心存储介质）
+ */
+type ResumePoint = {
+  /**
+   * 已完成的阶段（如 ['fetch']，这些阶段会被跳过）
+   */
+  completedStages?: PipelineStage[];
+  /**
+   * 当前位置 sha（fetch 跳过时作为 remoteTip）
+   */
+  currentPosition?: CommitSha;
+};
+/**
+ * hooks 回调（业务过程管理由调用方实现）
+ */
+type PipelineHooks = {
+  /**
+   * 阶段开始通知（调用方据此发布 task_stage_started 事件）
+   *
+   * 仅在实际执行的阶段触发（skipped 阶段不触发）。
+   */
+  onStageStarted?: (stage: PipelineStage) => Promise<void> | void;
+  /**
+   * 阶段完成通知（调用方据此存断点）
+   */
+  onStageCompleted?: (stage: PipelineStage, resultingSha: CommitSha | null, processedCount: number) => Promise<void> | void;
+  /**
+   * 进度回调转发（调用方据此上报到 progressPort / eventBus）
+   */
+  onProgress?: OnProgress;
+  /**
+   * 协作式取消检查（调用方返回 true 则在阶段切换处中止）
+   */
+  shouldCancel?: () => boolean;
+  /**
+   * 建议提示回调（调用方据此向用户展示建议，如"建议启用 LFS"）
+   *
+   * pipeline 在 LFS 探测发现"远端支持 LFS 但仓库未启用"时调用，
+   * 上抛建议给业务层。pipeline 自身不执行 LFS migrate（破坏性不可逆）。
+   */
+  onAdvice?: (advice: string) => Promise<void> | void;
+};
+/**
+ * pipeline 执行选项
+ */
+type PipelineOptions = {
+  /**
+   * git 执行器
+   */
+  executor: GitExecutor;
+  /**
+   * 仓库工作目录
+   */
+  repoPath: string;
+  /**
+   * 远端名
+   */
+  remote: string;
+  /**
+   * 目标 ref
+   */
+  ref: RefName;
+  /**
+   * 同步策略
+   */
+  strategy: SyncStrategy;
+  /**
+   * 分段大小
+   */
+  segmentSize: number;
+  /**
+   * fetch 停滞超时
+   */
+  stallTimeoutMs: number;
+  /**
+   * fetch 绝对超时
+   */
+  absoluteTimeoutMs: number;
+  /**
+   * rebase/merge/push 单阶段超时
+   */
+  stageTimeoutMs: number;
+  /**
+   * 单阶段重试次数
+   */
+  stageRetries: number;
+  /**
+   * 断点续传起点（缺省从头开始）
+   */
+  resumeFrom?: ResumePoint;
+  /**
+   * 是否启用 LFS 探测 + 透传，默认 true
+   *
+   * 启用后：
+   * - fetch 阶段起始处探测 LFS 三项状态（客户端/仓库/远端）
+   * - 仓库已启用 LFS → fetch 后透传 git lfs fetch，push 前透传 git lfs push
+   * - 远端支持但仓库未启用 → 上抛建议提示（不自动 migrate）
+   */
+  enableLfsPassthrough?: boolean;
+  /**
+   * hooks 回调
+   */
+  hooks?: PipelineHooks;
+};
+/**
+ * pipeline 执行结果
+ */
+type PipelineResult = {
+  /**
+   * 各阶段结果
+   */
+  stages: StageResult[];
+  /**
+   * 总耗时（ms）
+   */
+  totalDurationMs: number;
+};
+/**
+ * 创建 sync pipeline
+ *
+ * @param executor - GitExecutor 实例
+ * @returns 提供 execute 方法的执行编排管线
+ */
+declare const createSyncPipeline: (executor: GitExecutor) => {
+  execute: (options: PipelineOptions) => Promise<PipelineResult>;
+};
+//#endregion
+export { type PipelineHooks, type PipelineOptions, type PipelineResult, type PipelineStage, type ResumePoint, type StageResult, type SyncStrategy, createSyncPipeline };

package/dist/index.js

@@ -0,0 +1 @@
+import{CHECKOUT_FILE_THRESHOLD as e,PATCH_BYTE_THRESHOLD as t,createChunkedFetcher as n,createCommitSha as r,createIncrementalPusher as i,createMerger as a,createRefName as o,createSegmentedRebaser as s,detectStrategy as c,estimateRebaseCost as l,fetchLfs as u,probeLfs as d,pushLfs as f,withMassiveGuard as p}from"@longzai-intelligence-git/core";const m=e=>e<1024?`${e} B`:e<1048576?`${(e/1024).toFixed(1)} KB`:e<1073741824?`${(e/1048576).toFixed(1)} MB`:`${(e/1073741824).toFixed(1)} GB`,h=h=>({execute:async g=>{let _=Date.now(),v=[],y=g.hooks??{},b=()=>{if(y.shouldCancel?.()===!0)throw Error(`任务已取消`)},x=g.enableLfsPassthrough??!0,S=null;x&&(S=await d(h,g.repoPath,g.remote),S.clientInstalled&&S.remoteSupported&&!S.repoEnabled&&await y.onAdvice?.(`检测到远端支持 LFS（Git Large File Storage），但当前仓库未启用。仓库含大文件时，启用 LFS 可显著优化 fetch/push 传输（大文件不进 git pack）。请手动执行 git lfs install + git lfs migrate import 后重新同步。`));let C=g.resumeFrom?.completedStages?.includes(`fetch`)??!1,w;C?(w={remoteTip:g.resumeFrom?.currentPosition??null,durationMs:0,stallRetries:0,completeness:`tip`,layersFetched:0,refetchBatches:0},v.push({stage:`fetch`,status:`skipped`,durationMs:0,resultingSha:w.remoteTip,error:null})):(await y.onStageStarted?.(`fetch`),w=await n(h).fetch({repoPath:g.repoPath,remote:g.remote,ref:o(g.ref),stallTimeoutMs:g.stallTimeoutMs,absoluteTimeoutMs:g.absoluteTimeoutMs,maxStallRetries:g.stageRetries+2,onProgress:y.onProgress??null,fetchCompleteness:`full`,deepenStep:g.segmentSize,maxDeepenLayers:50,enableNegotiationOpt:!0}),v.push({stage:`fetch`,status:`completed`,durationMs:w.durationMs,resultingSha:w.remoteTip,error:null}),await y.onStageCompleted?.(`fetch`,w.remoteTip,w.stallRetries)),S?.repoEnabled===!0&&!C&&await u(h,{repoPath:g.repoPath,remote:g.remote,stallTimeoutMs:g.stallTimeoutMs,absoluteTimeoutMs:g.absoluteTimeoutMs,onProgress:y.onProgress??null}),b();let T,E=``;if(w.remoteTip!=null){E=(await p({executor:h,repoPath:g.repoPath,args:[`rev-parse`,`HEAD`],readOnly:!0,onStderrLine:()=>{}})).stdout.trim();let n=(await p({executor:h,repoPath:g.repoPath,args:[`merge-base`,E,w.remoteTip],readOnly:!0,onStderrLine:()=>{}})).stdout.trim(),i=await p({executor:h,repoPath:g.repoPath,args:[`rev-list`,`--count`,`${n}..${E}`],readOnly:!0,onStderrLine:()=>{}}),a=Number.parseInt(i.stdout,10)||0,o=await p({executor:h,repoPath:g.repoPath,args:[`rev-list`,`--count`,`${n}..${w.remoteTip}`],readOnly:!0,onStderrLine:()=>{}}),s=Number.parseInt(o.stdout,10)||0,u=c(r(E),w.remoteTip,r(n),a,s);if(u.strategy===`rebase`&&g.strategy===`fast_forward_only`)throw Error(`[策略校验失败] 实际分叉（本地领先 ${a}，远端领先 ${s}）需要 rebase/merge，但 strategy=fast_forward_only。禁止在分叉场景强制快进（会失败或诱发 force push 事故）。请改用 strategy=rebase（小差异）或 strategy=merge（大差异/平行链）。`);if(u.strategy===`rebase`&&g.strategy===`rebase`){let n=await l(h,g.repoPath,w.remoteTip,r(E)),i=n.patchFileUnionCount>e,a=n.patchFileBytes!=null&&n.patchFileBytes>t;if(i||a){let r=[`patch 触碰 ${n.patchFileUnionCount} 文件（阈值 ${e}）`];throw n.patchFileBytes!=null&&r.push(`累计 ${m(n.patchFileBytes)}（阈值 ${m(t)}）`),Error(`[D5 代价评估] 待重放 ${n.commitCount} commit 的 ${r.join(`，`)}。大差异/大文件 rebase 会触发大量 checkout（事故根因，见 issue 001/008）。平行链应使用 strategy=merge（保留两条链历史，只 checkout 一次）。请改用 strategy=merge。`)}}}if(g.strategy===`fast_forward_only`||w.remoteTip==null)T=r(E||``),v.push({stage:`rebase`,status:`skipped`,durationMs:0,resultingSha:T,error:null}),v.push({stage:`merge`,status:`skipped`,durationMs:0,resultingSha:T,error:null});else if(g.strategy===`merge`){v.push({stage:`rebase`,status:`skipped`,durationMs:0,resultingSha:null,error:null}),await y.onStageStarted?.(`merge`);let e=r(E),t=await a(h).merge({repoPath:g.repoPath,remote:g.remote,ref:o(g.ref),remoteTip:w.remoteTip,localTip:e,timeoutMs:g.stageTimeoutMs,retries:g.stageRetries,onProgress:y.onProgress??null});T=t.newLocalTip,v.push({stage:`merge`,status:`completed`,durationMs:t.durationMs,resultingSha:T,error:null}),await y.onStageCompleted?.(`merge`,T,+!!t.mergeCommitSha)}else{v.push({stage:`merge`,status:`skipped`,durationMs:0,resultingSha:null,error:null}),await y.onStageStarted?.(`rebase`);let e=r(E),t=await s(h).rebase({repoPath:g.repoPath,remote:g.remote,ref:o(g.ref),baseSha:w.remoteTip,localTip:e,segmentSize:g.segmentSize,timeoutMs:g.stageTimeoutMs,retries:g.stageRetries,onProgress:y.onProgress??null});T=t.newLocalTip,v.push({stage:`rebase`,status:`completed`,durationMs:t.durationMs,resultingSha:T,error:null}),await y.onStageCompleted?.(`rebase`,T,t.segmentsRebased)}if(b(),await y.onStageStarted?.(`push`),S?.repoEnabled===!0){let e=await f(h,{repoPath:g.repoPath,remote:g.remote,stallTimeoutMs:g.stallTimeoutMs,absoluteTimeoutMs:g.absoluteTimeoutMs,onProgress:y.onProgress??null},g.ref,r(T));if(!e.success)throw Error(`LFS push 失败（LFS 对象缺失会导致远端拒绝 commit）: ${e.error??`(无 stderr)`}`)}let D=await i(h).push({repoPath:g.repoPath,remote:g.remote,ref:o(g.ref),localTip:r(T),remoteCurrentSha:w.remoteTip??r(T),segmentSize:g.segmentSize,timeoutMs:g.stageTimeoutMs,retries:g.stageRetries,onProgress:y.onProgress??null});return v.push({stage:`push`,status:`completed`,durationMs:D.durationMs,resultingSha:D.remoteFinalSha,error:null}),{stages:v,totalDurationMs:Date.now()-_}}});export{h as createSyncPipeline};

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@longzai-intelligence-git/massive-sync-pipeline",
+  "version": "0.0.1",
+  "description": "Longzai Intelligence Git - 执行编排管线",
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "lzi-builder",
+    "build:prod": "NODE_ENV=production bun run build",
+    "prepublishOnly": "bun run build:prod",
+    "typecheck": "bun run typecheck:app && bun run typecheck:node && bun run typecheck:test",
+    "typecheck:app": "lzi-tsgo typecheck tsconfig/app.json",
+    "typecheck:node": "lzi-tsgo typecheck tsconfig/node.json",
+    "typecheck:test": "lzi-tsgo typecheck tsconfig/test.json",
+    "lint": "oxlint && oxfmt --check",
+    "lint:fix": "oxlint --fix && oxfmt",
+    "test": "bun test",
+    "test:watch": "bun test --watch",
+    "test:coverage": "bun test --coverage",
+    "clean": "lzi-dev-cli clean"
+  },
+  "dependencies": {
+    "@longzai-intelligence-git/core": "0.0.1"
+  },
+  "peerDependencies": {
+    "zod": "^4.4.3"
+  }
+}