@co-engram/core 0.1.2 → 0.1.3

package/dist/storage/git.d.ts

@@ -4,6 +4,11 @@
  * 不依赖外部 npm 包，保持 host-agnostic。
  * 只封装 co-engram 需要的最小操作集。
  *
+ * 公司内外部兼容性策略:
+ *   - 直接调用系统 `git`,继承用户 SSH/credentials/proxy 环境
+ *   - 不硬编码任何主机名/URL/refspec(Gerrit review 由用户 .git/config 决定)
+ *   - 不主动写 Change-Id(ZTE/Gerrit commit-msg hook 若已装会自动加)
+ *
  * @module @co-engram/core/storage
  */
 /** Git 提交选项 */
@@ -36,6 +41,11 @@ export declare function initGitRepo(repoPath: string): void;
  * Stage 文件并提交
  *
  * 注意：不会自动 push，团队需要时手动 push。
+ *
+ * 实现安全说明(Task 4.2):用 `spawnSync` + 数组参数(`args[]`)而非
+ * `execSync` + 字符串拼接,避免 shell 元字符(backtick / $ / 反引号)
+ * 在 authorName / message / file 路径里触发命令注入。数组参数下 git
+ * 直接收到原始字符串,不经 shell 解释。
  */
 export declare function commitFiles(options: GitCommitOptions): GitCommitResult;
 /**
@@ -54,4 +64,162 @@ export declare function getFileLastCommit(repoPath: string, relativePath: string
  * 获取仓库根目录的绝对路径
  */
 export declare function resolveRepoPath(repoPath: string): string;
+/** `git pull` 结果 */
+export interface GitPullResult {
+    /** 是否成功(无冲突) */
+    readonly ok: boolean;
+    /** 远端无新内容(已是最新) */
+    readonly upToDate?: boolean;
+    /** rebase 冲突文件清单(相对仓库根路径);ok=false 时填 */
+    readonly conflicts?: readonly string[];
+    /** 合并/快进的提交数(upToDate=true 时为 0) */
+    readonly fetchedCount?: number;
+}
+/**
+ * `git pull --rebase` —— 用 rebase 策略保持线性历史。
+ *
+ * 冲突时执行 `git rebase --abort` 回到 pull 前状态,并返回 conflicts 清单,
+ * 让调用方决定下一步(人工解决 / 放弃)。绝不自动 resolve。
+ *
+ * 远端无新提交时返回 `{ ok: true, upToDate: true }`。
+ *
+ * 注意:调用方需保证 repoPath 是 git 仓库(用 isGitRepo 预检)。
+ */
+export declare function pullRepo(repoPath: string): GitPullResult;
+/** `git push` 结果 */
+export interface GitPushResult {
+    /** 是否成功 */
+    readonly ok: boolean;
+    /** 是否被跳过(无 remote / push=false / 无 upstream) */
+    readonly skipped: boolean;
+    /** 跳过/失败原因 */
+    readonly reason?: string;
+    /** push 到的 remote 名称(如 "origin") */
+    readonly remote?: string;
+    /** 实际生效的 push 模式:direct = 普通 push;gerrit-review = 走 refs/for/<branch> review */
+    readonly mode?: "direct" | "gerrit-review";
+    /** 仅在 direct 拒绝后自动 fallback 到 gerrit-review 成功时为 true */
+    readonly autoFallback?: true;
+}
+/**
+ * 检测 stderr 是否是 Gerrit 对受保护分支的拒绝特征。
+ *
+ * Gerrit 对 master 等受保护分支的直接 push 返回 "prohibited by Gerrit"
+ * 或 "need 'Push' rights"。命中后可 fallback 到 `refs/for/<branch>` 走 review。
+ */
+export declare function isGerritRejection(stderr: string): boolean;
+/**
+ * `git push` —— 推送当前分支,失败时若检测到 Gerrit 拒绝则自动 fallback 到 review。
+ *
+ * 行为:
+ *   - 有 upstream → `git push`(尊重 push.default 配置)
+ *   - 无 upstream → `git push --set-upstream <remote> <branch>`
+ *   - 任一路径失败且 stderr 命中 Gerrit 拒绝特征 → 自动重试
+ *     `git push <remote> HEAD:refs/for/<branch>`(spawnSync 数组参数,防注入)
+ *
+ * 兼容 GitHub / GitLab / Gerrit / 内部 Git 服务,不硬编码 URL 或 refspec。
+ * Gerrit 用户无需手动配置 .git/config 的 `push = refs/heads/*:refs/for/*`,
+ * 检测到 direct push 被拒即自动走 review(返回 mode="gerrit-review", autoFallback=true)。
+ *
+ * 不抛错 —— 返回结构化结果让工具层向用户报告。
+ */
+export declare function pushRepo(repoPath: string): GitPushResult;
+/**
+ * 获取 `git status --short` 解析后的变更清单。
+ *
+ * 用于 dryRun 预览 + 提交后校验 filesChanged。
+ * 返回相对仓库根的路径数组(去重 + 排序,确保跨平台一致)。
+ */
+export declare function getGitStatusShort(repoPath: string): readonly string[];
+/**
+ * 是否配置了 git remote。
+ *
+ * 用于工具层在 push=true 时预判"无 remote → commit-only 降级"路径。
+ */
+export declare function hasRemote(repoPath: string): boolean;
+/**
+ * 默认 .gitignore 模板(co-engram 仓库)。
+ *
+ * 设计原则:整个 `.co-engram/` 目录不入库(派生数据 + 行为缓存 +
+ * 审计日志,均可重新生成或本地保留),只跟踪用户内容(*.md, synapses/)。
+ *
+ * Obsidian 用户态文件(workspace.json 等)每台机器不同,不入库;
+ * 团队级配置(app.json, appearance.json 等)可入库,由用户决定。
+ */
+export declare const DEFAULT_CO_ENGRAM_GITIGNORE = "# co-engram \u4ED3\u5E93\u9ED8\u8BA4 .gitignore\n# \u6574\u4E2A .co-engram/ \u76EE\u5F55\u4E0D\u5165\u5E93(\u6D3E\u751F\u6570\u636E + \u884C\u4E3A\u7F13\u5B58 + \u5BA1\u8BA1\u65E5\u5FD7,\u53EF\u91CD\u65B0\u751F\u6210)\n.co-engram/\n\n# Private engrams(visibility='private')\u2014\u2014 \u7528\u6237\u79C1\u4EBA\u8BB0\u5FC6,\u4E0D\u5165\u56E2\u961F\u4ED3\u5E93\n# \u672C\u673A agent \u4ECD\u53EF\u7D22\u5F15/\u68C0\u7D22;\u53EA\u5728 git sync \u5C42\u9694\u79BB\u3002\n# \u7528\u6237\u82E5\u60F3\u4FDD\u7559 private engram \u7684 git \u5386\u53F2,\u53EF\u5728 private/ \u5B50\u76EE\u5F55\u5EFA\u72EC\u7ACB git \u4ED3\u5E93\u3002\nprivate/\n\n# Obsidian \u7528\u6237\u6001(\u6BCF\u53F0\u673A\u5668\u4E0D\u540C)\n.obsidian/workspace.json\n.obsidian/workspace-mobile.json\n.obsidian/workspace.json.bak\n.obsidian/cache\n.obsidian/plugins/*/data.json\n\n# \u7CFB\u7EDF\n.DS_Store\nThumbs.db\n*.swp\n*.swo\n";
+/**
+ * 若缺失则创建 .gitignore(用 DEFAULT_CO_ENGRAM_GITIGNORE 模板)。
+ *
+ * @returns true 表示本次创建,false 表示已存在未动。
+ */
+export declare function ensureGitignore(repoPath: string): boolean;
+/**
+ * 向已存在的 .gitignore 追加规则(幂等)。
+ *
+ * 用于让历史已存在的 .gitignore 升级,补上新规则(如 `private/`)。
+ * 与 `ensureGitignore` 互补:后者只处理"文件不存在"场景。
+ *
+ * 幂等性:若 .gitignore 已含相同 rule 行(忽略首尾空白),不重复追加。
+ *
+ * @returns true 表示本次追加,false 表示已含该 rule 或 .gitignore 不存在。
+ */
+export declare function appendToGitignore(repoPath: string, rule: string): boolean;
+/**
+ * 把 `.co-engram/` 目录从 git index 移除(磁盘文件保留)。
+ *
+ * `.gitignore` 只对未 track 的文件生效;若历史 commit 已 track 了
+ * `.co-engram/*`,新建 .gitignore 后这些文件仍会被 commit。
+ *
+ * 本函数检测这一情况,若已 track 则 `git rm -r --cached --quiet .co-engram/`,
+ * 让缓存目录真正退出 git 跟踪(磁盘文件原样保留,不影响运行时)。
+ *
+ * **重要副作用:** commit 描述是"删除这些文件"。协作者 pull 此 commit 时,
+ * 他们本地的 `.co-engram/*` 磁盘文件也会被 git 删除(因为 commit 说删)。
+ * 若协作者本地有不可再生的数据(如 audit.jsonl 团队审计),会丢失。
+ * 调用方应让用户显式 opt-in,而非默认执行。
+ *
+ * @returns 移除的文件数(0 = 本来就没 track 或失败)。
+ */
+export declare function untrackCoEngramCache(repoPath: string): number;
+/**
+ * 只读检测:`.co-engram/` 下已 tracked 的文件数(不修改 index)。
+ *
+ * 用于 dryRun 预测 + 工具层判断是否需要提示用户 opt-in untrack。
+ */
+export declare function countTrackedCoEngramCache(repoPath: string): number;
+/**
+ * 把 `private/` 目录从 git index 移除(磁盘文件保留)。
+ *
+ * `private/` 已加入 DEFAULT_CO_ENGRAM_GITIGNORE,新文件自动跳过;
+ * 但历史 commit 已 track 的 `private/*.md` 仍会被 commit,需显式 untrack。
+ *
+ * **重要副作用(比 `.co-engram/` 更危险):** private engram 是用户私人记忆,
+ * commit 描述是"删除这些文件"。协作者 pull 时,他们本地 `private/*.md` 也会被
+ * git 删除 —— 而 private 通常**不可再生**(用户的个人凭据/路径/偏好)。
+ *
+ * 调用方必须:
+ * 1. dryRun 预览,明确告知"会从 git 移除 N 个 private 文件";
+ * 2. 让用户显式 opt-in(不能默认执行);
+ * 3. 提示用户:本机磁盘文件保留,但跨机历史已被抹去。
+ *
+ * @returns 移除的文件数(0 = 本来就没 track 或失败)。
+ */
+export declare function untrackPrivateDir(repoPath: string): number;
+/**
+ * 只读检测:`private/` 下已 tracked 的文件数(不修改 index)。
+ *
+ * 用于 dryRun 预测 + 工具层判断是否需要提示用户 opt-in untrack。
+ */
+export declare function countTrackedPrivateDir(repoPath: string): number;
+/**
+ * 读取 .gitignore 内容(用于诊断/展示)。不存在返回 null。
+ */
+export declare function readGitignore(repoPath: string): string | null;
+/**
+ * 只读检测:.gitignore 是否已含指定 rule(逐行 trim 后比对)。
+ *
+ * 与 `appendToGitignore` 的检测逻辑镜像,但不写盘。
+ * 用于 dryRun 预测:engram_sync 在只读模式下判断是否需要追加 private/。
+ */
+export declare function gitignoreContainsRule(repoPath: string, rule: string): boolean;
 //# sourceMappingURL=git.d.ts.map

package/dist/storage/git.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"git.d.ts","sourceRoot":"","sources":["../../src/storage/git.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAMH,eAAe;AACf,MAAM,WAAW,gBAAgB;IAC/B,YAAY;IACZ,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,mBAAmB;IACnB,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,WAAW;IACX,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,wBAAwB;IACxB,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,eAAe;AACf,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAanD;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAclD;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,gBAAgB,GAAG,eAAe,CA8DtE;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CASzD;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,MAAM,GACnB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAwBxD;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAKxD"}
+{"version":3,"file":"git.d.ts","sourceRoot":"","sources":["../../src/storage/git.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAMH,eAAe;AACf,MAAM,WAAW,gBAAgB;IAC/B,YAAY;IACZ,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,mBAAmB;IACnB,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,WAAW;IACX,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,wBAAwB;IACxB,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,eAAe;AACf,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAanD;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAclD;AAED;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,gBAAgB,GAAG,eAAe,CAiEtE;AAoCD;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CASzD;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,MAAM,GACnB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAwBxD;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAKxD;AAMD,oBAAoB;AACpB,MAAM,WAAW,aAAa;IAC5B,gBAAgB;IAChB,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;IACrB,mBAAmB;IACnB,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC5B,yCAAyC;IACzC,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC,oCAAoC;IACpC,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;CAChC;AAED;;;;;;;;;GASG;AACH,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,aAAa,CAmExD;AAqBD,oBAAoB;AACpB,MAAM,WAAW,aAAa;IAC5B,WAAW;IACX,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;IACrB,gDAAgD;IAChD,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,cAAc;IACd,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,oCAAoC;IACpC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,gFAAgF;IAChF,QAAQ,CAAC,IAAI,CAAC,EAAE,QAAQ,GAAG,eAAe,CAAC;IAC3C,yDAAyD;IACzD,QAAQ,CAAC,YAAY,CAAC,EAAE,IAAI,CAAC;CAC9B;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAEzD;AA+ED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,aAAa,CAiExD;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAuBrE;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAcnD;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,2BAA2B,04BAqBvC,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAOzD;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAsBzE;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CA6B7D;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAclE;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CA4B1D;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAc/D;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAQ7D;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAM7E"}