@co-engram/core 0.1.0 → 0.1.1

package/dist/merge/merge-engram.js

@@ -0,0 +1,164 @@
+/**
+ * Engram 文件合并入口
+ *
+ * 组装 frontmatter 合并 + content 合并 + 收尾(contentHash / contentSize 重算,
+ * updatedAt 取 max, version 取 max+1, updatedBy='merge-driver')。
+ * 失败模式:任一方解析失败 → throw;frontmatter/content escalate → 用 git marker
+ * 形式包装输给 driver 写 %A + exit 1。
+ *
+ * @module @co-engram/core/merge
+ */
+import { createHash } from "node:crypto";
+import { parseEngramFile, serializeEngramFile, detectEngramFileLanguage, } from "../storage/engram-store.js";
+import { mergeFrontmatter, mergeFrontmatterAsync } from "./frontmatter.js";
+import { mergeContent, mergeContentAsync } from "./content.js";
+import { snapshotLoser } from "./backup.js";
+function computeContentHashAndSize(content) {
+    const hash = createHash("sha256").update(content, "utf8").digest("hex");
+    const size = Buffer.byteLength(content, "utf8");
+    return { hash, size };
+}
+function buildEscalatedContent(oursRaw, theirsRaw) {
+    return `<<<<<<< ours\n${oursRaw}\n=======\n${theirsRaw}\n>>>>>>> theirs\n`;
+}
+export async function mergeEngramFile(params) {
+    const { baseRaw, oursRaw, theirsRaw, relPath, dataRoot, auditLog } = params;
+    // Step 1: Parse (may throw — caller exits 1)
+    const baseFile = parseEngramFile(baseRaw);
+    const oursFile = parseEngramFile(oursRaw);
+    const theirsFile = parseEngramFile(theirsRaw);
+    // Detect language from base (fallback to ours / theirs) so output preserves input format.
+    const language = detectEngramFileLanguage(baseRaw) ??
+        detectEngramFileLanguage(oursRaw) ??
+        detectEngramFileLanguage(theirsRaw);
+    // Step 2: Frontmatter merge (with optional LLM Layer B)
+    const fmOutcome = params.llmArbiter
+        ? await mergeFrontmatterAsync({
+            base: baseFile.frontmatter,
+            ours: oursFile.frontmatter,
+            theirs: theirsFile.frontmatter,
+            arbiter: params.llmArbiter,
+            path: relPath,
+            meta: {
+                oursUpdatedAt: oursFile.frontmatter.updatedAt,
+                theirsUpdatedAt: theirsFile.frontmatter.updatedAt,
+                oursUpdatedBy: oursFile.frontmatter.updatedBy ?? "unknown",
+                theirsUpdatedBy: theirsFile.frontmatter.updatedBy ?? "unknown",
+            },
+        })
+        : mergeFrontmatter({
+            base: baseFile.frontmatter,
+            ours: oursFile.frontmatter,
+            theirs: theirsFile.frontmatter,
+        });
+    // Step 3: Content merge (with optional LLM Layer B)
+    const contentOutcome = params.llmArbiter
+        ? await mergeContentAsync({
+            base: baseFile.content,
+            ours: oursFile.content,
+            theirs: theirsFile.content,
+            oursUpdatedAt: oursFile.frontmatter.updatedAt,
+            theirsUpdatedAt: theirsFile.frontmatter.updatedAt,
+            oursUpdatedBy: oursFile.frontmatter.updatedBy,
+            theirsUpdatedBy: theirsFile.frontmatter.updatedBy,
+            arbiter: params.llmArbiter,
+            path: relPath,
+        })
+        : mergeContent({
+            base: baseFile.content,
+            ours: oursFile.content,
+            theirs: theirsFile.content,
+            oursUpdatedAt: oursFile.frontmatter.updatedAt,
+            theirsUpdatedAt: theirsFile.frontmatter.updatedAt,
+        });
+    // Step 4: Decide escalation
+    const escalated = fmOutcome.escalatedFields.length > 0 ||
+        contentOutcome.strategy === "escalate";
+    if (escalated) {
+        const strategyParts = [];
+        if (fmOutcome.escalatedFields.length > 0) {
+            strategyParts.push(`frontmatter-escalate:${fmOutcome.escalatedFields.join(",")}`);
+        }
+        if (contentOutcome.strategy === "escalate") {
+            strategyParts.push("content-escalate:updatedAt-collision");
+        }
+        return {
+            mergedContent: buildEscalatedContent(oursRaw, theirsRaw),
+            strategy: `escalate(${strategyParts.join(" + ")})`,
+            winner: null,
+            escalated: true,
+        };
+    }
+    // Step 5: Recompute contentHash / contentSize + finalize
+    // updatedAt / version are 'max' fields — orchestrator already computed max(ours, theirs).
+    // Per spec §4.5 we additionally:
+    //   - bump version by +1 (merge produces a new state)
+    //   - set updatedBy = 'merge-driver'
+    const { hash, size } = computeContentHashAndSize(contentOutcome.merged);
+    const oursVersion = oursFile.frontmatter.version ?? 0;
+    const theirsVersion = theirsFile.frontmatter.version ?? 0;
+    const mergedFm = {
+        ...fmOutcome.merged,
+        contentHash: hash,
+        contentSize: size,
+        updatedBy: "merge-driver",
+        version: Math.max(oursVersion, theirsVersion) + 1,
+    };
+    // fmOutcome.merged.updatedAt is already max(ours, theirs) via the 'max' rule; leave as-is.
+    // Guard against the case where both sides omitted updatedAt (rare; treat as Date.now).
+    if (mergedFm.updatedAt === undefined) {
+        mergedFm.updatedAt = new Date().toISOString();
+    }
+    const mergedFile = {
+        frontmatter: mergedFm,
+        content: contentOutcome.merged,
+    };
+    const serialized = serializeEngramFile(mergedFile, language);
+    // Step 6: Backup + audit
+    let backupPath;
+    const loserSide = contentOutcome.winner === "ours"
+        ? "theirs"
+        : contentOutcome.winner === "theirs"
+            ? "ours"
+            : null;
+    if (loserSide && dataRoot) {
+        try {
+            const backup = snapshotLoser({
+                dataRoot,
+                relPath,
+                side: loserSide,
+                content: loserSide === "ours" ? oursRaw : theirsRaw,
+            });
+            backupPath = backup.backupPath;
+        }
+        catch (e) {
+            auditLog?.append({
+                actor: "system",
+                action: "merge_backup_failed",
+                metadata: {
+                    path: relPath,
+                    reason: e instanceof Error ? e.message : String(e),
+                },
+            });
+        }
+    }
+    auditLog?.append({
+        actor: "system",
+        action: "merge_resolved",
+        engramId: mergedFm.id,
+        metadata: {
+            path: relPath,
+            strategy: `${fmOutcome.strategy} + ${contentOutcome.strategy}`,
+            winner: contentOutcome.winner ?? fmOutcome.arbitratedWinner,
+            backupPath,
+        },
+    });
+    return {
+        mergedContent: serialized,
+        strategy: `${fmOutcome.strategy} + ${contentOutcome.strategy}`,
+        winner: contentOutcome.winner ?? fmOutcome.arbitratedWinner,
+        escalated: false,
+        backupPath,
+    };
+}
+//# sourceMappingURL=merge-engram.js.map

package/dist/merge/merge-engram.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"merge-engram.js","sourceRoot":"","sources":["../../src/merge/merge-engram.ts"],"names":[],"mappings":"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"}

package/dist/merge/merge-stats.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Merge statistics (spec §7.4, §9) — 从 audit log 聚合 merge driver 指标。
+ *
+ * 用途:
+ *   - `co-engram merge stats` CLI 输出
+ *   - viewer "Merges" tab 数据源
+ *   - anomaly detection(P4.4)的输入
+ *
+ * 设计:纯函数 + 注入 AuditLog,便于测试。
+ *
+ * @module @co-engram/core/merge
+ */
+import type { AuditLog } from "../observability/audit-log.js";
+/** 默认统计窗口:7 天(spec §9 operational window)。 */
+export declare const DEFAULT_STATS_WINDOW_DAYS = 7;
+export interface MergeStatsWindow {
+    readonly since: string;
+    readonly until: string;
+}
+export interface MergeStats {
+    readonly window: MergeStatsWindow;
+    /** 总 merge 处理数(resolved + escalated)。 */
+    readonly totalMerges: number;
+    /** 自动解决数(merge_resolved)。 */
+    readonly autoResolved: number;
+    /** 升级到 markers 的冲突数(merge_conflict_escalated)。 */
+    readonly escalatedToMarkers: number;
+    /** LLM 介入统计。 */
+    readonly llm: LlmStats;
+    /** Backup 失败数(spec §9 健康指标)。 */
+    readonly backupFailures: number;
+    /** 自动解决率 [0,1] = autoResolved / totalMerges。 */
+    readonly autoResolveRate: number;
+    /** 按策略(strategy)分组的解决计数(metadata.reason)。 */
+    readonly byStrategy: Readonly<Record<string, number>>;
+    /** 按路径分组的冲突计数(metadata.path)。 */
+    readonly byPath: Readonly<Record<string, number>>;
+    /** 按天聚合的 merge 总数(YYYY-MM-DD → count),用于趋势分析。 */
+    readonly byDay: Readonly<Record<string, number>>;
+}
+export interface LlmStats {
+    /** LLM 成功仲裁数(merge_llm_arbitrated)。 */
+    readonly arbitrated: number;
+    /** LLM 介入但 escalate 的数(置信度不够等)。 */
+    readonly escalated: number;
+    /** LLM 调用失败数(网络 / parse / timeout)。 */
+    readonly failed: number;
+    /** LLM 总调用尝试 = arbitrated + escalated + failed。 */
+    readonly totalInvocations: number;
+    /** 成功率 [0,1] = arbitrated / totalInvocations。 */
+    readonly successRate: number;
+}
+/**
+ * 聚合 audit log 为 merge 统计。
+ *
+ * @param auditLog 要读取的 audit log
+ * @param windowMs 时间窗口(默认 7 天),从 now 向前回溯
+ */
+export declare function computeMergeStats(params: {
+    auditLog: AuditLog;
+    windowMs?: number;
+    now?: () => Date;
+}): MergeStats;
+/**
+ * 把 MergeStats 格式化成人类可读的文本(供 CLI 使用)。
+ */
+export declare function formatMergeStatsAsText(stats: MergeStats): string;
+//# sourceMappingURL=merge-stats.d.ts.map

package/dist/merge/merge-stats.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"merge-stats.d.ts","sourceRoot":"","sources":["../../src/merge/merge-stats.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EACV,QAAQ,EAGT,MAAM,+BAA+B,CAAC;AAYvC,8CAA8C;AAC9C,eAAO,MAAM,yBAAyB,IAAI,CAAC;AAE3C,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC;IAClC,yCAAyC;IACzC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,6BAA6B;IAC7B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,kDAAkD;IAClD,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,gBAAgB;IAChB,QAAQ,CAAC,GAAG,EAAE,QAAQ,CAAC;IACvB,gCAAgC;IAChC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,gDAAgD;IAChD,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,6CAA6C;IAC7C,QAAQ,CAAC,UAAU,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACtD,iCAAiC;IACjC,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAClD,iDAAiD;IACjD,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CAClD;AAED,MAAM,WAAW,QAAQ;IACvB,uCAAuC;IACvC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,mCAAmC;IACnC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,uCAAuC;IACvC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,mDAAmD;IACnD,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,iDAAiD;IACjD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE;IACxC,QAAQ,EAAE,QAAQ,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;CAClB,GAAG,UAAU,CAiBb;AA2ED;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CA4ChE"}

package/dist/merge/merge-stats.js

@@ -0,0 +1,152 @@
+/**
+ * Merge statistics (spec §7.4, §9) — 从 audit log 聚合 merge driver 指标。
+ *
+ * 用途:
+ *   - `co-engram merge stats` CLI 输出
+ *   - viewer "Merges" tab 数据源
+ *   - anomaly detection(P4.4)的输入
+ *
+ * 设计:纯函数 + 注入 AuditLog,便于测试。
+ *
+ * @module @co-engram/core/merge
+ */
+/** Merge-related audit actions(spec §5.5 + §9)。 */
+const MERGE_ACTIONS = [
+    "merge_resolved",
+    "merge_conflict_escalated",
+    "merge_backup_failed",
+    "merge_llm_arbitrated",
+    "merge_llm_arbitrated_escalated",
+    "merge_llm_arbitrated_failed",
+];
+/** 默认统计窗口:7 天(spec §9 operational window)。 */
+export const DEFAULT_STATS_WINDOW_DAYS = 7;
+/**
+ * 聚合 audit log 为 merge 统计。
+ *
+ * @param auditLog 要读取的 audit log
+ * @param windowMs 时间窗口(默认 7 天),从 now 向前回溯
+ */
+export function computeMergeStats(params) {
+    const { auditLog, now = () => new Date() } = params;
+    const windowMs = params.windowMs ?? DEFAULT_STATS_WINDOW_DAYS * 24 * 60 * 60 * 1000;
+    const until = now();
+    const since = new Date(until.getTime() - windowMs);
+    const sinceIso = since.toISOString();
+    const untilIso = until.toISOString();
+    const entries = auditLog.query({
+        since: sinceIso,
+        until: untilIso,
+        action: MERGE_ACTIONS,
+    });
+    return aggregateEntries(entries, { since: sinceIso, until: untilIso });
+}
+function aggregateEntries(entries, window) {
+    let autoResolved = 0;
+    let escalatedToMarkers = 0;
+    let backupFailures = 0;
+    let llmArbitrated = 0;
+    let llmEscalated = 0;
+    let llmFailed = 0;
+    const byStrategy = {};
+    const byPath = {};
+    const byDay = {};
+    for (const entry of entries) {
+        // 按天聚合(YYYY-MM-DD)
+        const day = entry.ts.slice(0, 10);
+        byDay[day] = (byDay[day] ?? 0) + 1;
+        switch (entry.action) {
+            case "merge_resolved":
+                autoResolved++;
+                if (entry.metadata?.reason) {
+                    const reason = String(entry.metadata.reason);
+                    byStrategy[reason] = (byStrategy[reason] ?? 0) + 1;
+                }
+                break;
+            case "merge_conflict_escalated":
+                escalatedToMarkers++;
+                if (entry.metadata?.path) {
+                    const p = String(entry.metadata.path);
+                    byPath[p] = (byPath[p] ?? 0) + 1;
+                }
+                break;
+            case "merge_backup_failed":
+                backupFailures++;
+                break;
+            case "merge_llm_arbitrated":
+                llmArbitrated++;
+                break;
+            case "merge_llm_arbitrated_escalated":
+                llmEscalated++;
+                break;
+            case "merge_llm_arbitrated_failed":
+                llmFailed++;
+                break;
+        }
+    }
+    const totalMerges = autoResolved + escalatedToMarkers;
+    const llmTotal = llmArbitrated + llmEscalated + llmFailed;
+    return {
+        window,
+        totalMerges,
+        autoResolved,
+        escalatedToMarkers,
+        llm: {
+            arbitrated: llmArbitrated,
+            escalated: llmEscalated,
+            failed: llmFailed,
+            totalInvocations: llmTotal,
+            successRate: llmTotal === 0 ? 0 : llmArbitrated / llmTotal,
+        },
+        backupFailures,
+        autoResolveRate: totalMerges === 0 ? 0 : autoResolved / totalMerges,
+        byStrategy,
+        byPath,
+        byDay,
+    };
+}
+/**
+ * 把 MergeStats 格式化成人类可读的文本(供 CLI 使用)。
+ */
+export function formatMergeStatsAsText(stats) {
+    const lines = [];
+    const w = stats.window;
+    lines.push(`co-engram merge stats`);
+    lines.push(`  window: ${w.since} → ${w.until}`);
+    lines.push(`  `);
+    lines.push(`  total merges:       ${stats.totalMerges}`);
+    lines.push(`  auto-resolved:      ${stats.autoResolved} (${pct(stats.autoResolveRate)})`);
+    lines.push(`  escalated(markers): ${stats.escalatedToMarkers}`);
+    lines.push(`  `);
+    lines.push(`  LLM arbitration:`);
+    lines.push(`    total:       ${stats.llm.totalInvocations}`);
+    lines.push(`    succeeded:   ${stats.llm.arbitrated}`);
+    lines.push(`    escalated:   ${stats.llm.escalated}`);
+    lines.push(`    failed:      ${stats.llm.failed}`);
+    lines.push(`    success rate:${pct(stats.llm.successRate)}`);
+    lines.push(`  `);
+    lines.push(`  backup failures:    ${stats.backupFailures}`);
+    // Top strategies
+    const strategies = Object.entries(stats.byStrategy).sort((a, b) => b[1] - a[1]);
+    if (strategies.length > 0) {
+        lines.push(`  `);
+        lines.push(`  top strategies:`);
+        for (const [s, n] of strategies.slice(0, 5)) {
+            lines.push(`    ${n.toString().padStart(5)}  ${s}`);
+        }
+    }
+    // Hot paths
+    const paths = Object.entries(stats.byPath).sort((a, b) => b[1] - a[1]);
+    if (paths.length > 0) {
+        lines.push(`  `);
+        lines.push(`  hot paths (most conflicts):`);
+        for (const [p, n] of paths.slice(0, 5)) {
+            lines.push(`    ${n.toString().padStart(5)}  ${p}`);
+        }
+    }
+    return lines.join("\n") + "\n";
+}
+function pct(r) {
+    return `${(r * 100).toFixed(1)}%`;
+}
+//# sourceMappingURL=merge-stats.js.map

package/dist/merge/merge-stats.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"merge-stats.js","sourceRoot":"","sources":["../../src/merge/merge-stats.ts"],"names":[],"mappings":"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"}

package/dist/merge/onboard.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Onboard: install/uninstall/status for the merge driver in a git repo.
+ *
+ * Phase 1: invoked manually by tests.
+ * Phase 2: wired into plugin onboarding + `co-engram git enable/disable/status`.
+ *
+ * installMergeDriver:
+ *  1. Copy the esbuild bundle to `~/.co-engram/merge-driver.cjs` (version-checked).
+ *  2. Write `[merge "co-engram"]` block into the repo's `.git/config`.
+ *  3. Append the merge=co-engram entry to `.gitattributes` (idempotent).
+ *
+ * uninstallMergeDriver (spec §8.8):
+ *  - Removes `merge.co-engram.*` keys from `.git/config`.
+ *  - DOES NOT remove .gitattributes entries (committed; affects whole team).
+ *  - DOES NOT remove ~/.co-engram/merge-driver.cjs (shared across repos).
+ *    Use uninstallGlobalBundle() for that.
+ *
+ * @module @co-engram-core/merge
+ */
+export declare const GITATTRIBUTES_ENTRY = "# co-engram structured merge driver\n**/*.md            merge=co-engram\nsynapses/**/*.yaml merge=co-engram\n";
+export interface OnboardResult {
+    readonly bundlePath: string;
+    readonly bundleUpgraded: boolean;
+    readonly gitConfigWritten: boolean;
+    readonly gitattributesUpdated: boolean;
+}
+export declare function installMergeDriver(params: {
+    repoRoot: string;
+    bundleSourcePath: string;
+}): OnboardResult;
+export interface OnboardStatus {
+    /** True if ~/.co-engram/merge-driver.cjs exists and matches the current version. */
+    readonly bundleInstalled: boolean;
+    /** The version banner in the installed bundle, or null if missing. */
+    readonly installedVersion: string | null;
+    /** True if .git/config has merge.co-engram.name. */
+    readonly gitConfigPresent: boolean;
+    /** True if .gitattributes contains merge=co-engram. */
+    readonly gitattributesPresent: boolean;
+    /** Absolute path to the bundle. */
+    readonly bundlePath: string;
+}
+export interface UninstallResult {
+    /** True if .git/config merge.co-engram.* keys were removed. */
+    readonly gitConfigRemoved: boolean;
+    /** True if ~/.co-engram/merge-driver.cjs was removed. */
+    readonly bundleRemoved: boolean;
+}
+/**
+ * Read the current onboard status for diagnostic / `co-engram git status` use.
+ */
+export declare function getOnboardStatus(params: {
+    repoRoot: string;
+}): OnboardStatus;
+/**
+ * Uninstall merge driver from the repo (spec §8.8).
+ *
+ * Removes .git/config merge.co-engram.* keys. Does NOT touch:
+ *   - .gitattributes (committed; affects whole team — user decides)
+ *   - ~/.co-engram/merge-driver.cjs (shared across repos — use uninstallGlobalBundle)
+ */
+export declare function uninstallMergeDriver(params: {
+    repoRoot: string;
+}): UninstallResult;
+/**
+ * Remove the global bundle (~/.co-engram/merge-driver.cjs).
+ * Spec §8.8: explicit `co-engram git uninstall --global` only.
+ */
+export declare function uninstallGlobalBundle(): {
+    bundleRemoved: boolean;
+};
+//# sourceMappingURL=onboard.d.ts.map

package/dist/merge/onboard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"onboard.d.ts","sourceRoot":"","sources":["../../src/merge/onboard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAeH,eAAO,MAAM,mBAAmB,kHAG/B,CAAC;AAKF,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;IACjC,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAC;IACnC,QAAQ,CAAC,oBAAoB,EAAE,OAAO,CAAC;CACxC;AAaD,wBAAgB,kBAAkB,CAAC,MAAM,EAAE;IACzC,QAAQ,EAAE,MAAM,CAAC;IACjB,gBAAgB,EAAE,MAAM,CAAC;CAC1B,GAAG,aAAa,CAsChB;AAED,MAAM,WAAW,aAAa;IAC5B,oFAAoF;IACpF,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC;IAClC,sEAAsE;IACtE,QAAQ,CAAC,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IACzC,oDAAoD;IACpD,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAC;IACnC,uDAAuD;IACvD,QAAQ,CAAC,oBAAoB,EAAE,OAAO,CAAC;IACvC,mCAAmC;IACnC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,eAAe;IAC9B,+DAA+D;IAC/D,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAC;IACnC,yDAAyD;IACzD,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;CACjC;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,GAAG,aAAa,CA4B5E;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE;IAC3C,QAAQ,EAAE,MAAM,CAAC;CAClB,GAAG,eAAe,CAclB;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,IAAI;IAAE,aAAa,EAAE,OAAO,CAAA;CAAE,CAUlE"}

package/dist/merge/onboard.js

@@ -0,0 +1,146 @@
+/**
+ * Onboard: install/uninstall/status for the merge driver in a git repo.
+ *
+ * Phase 1: invoked manually by tests.
+ * Phase 2: wired into plugin onboarding + `co-engram git enable/disable/status`.
+ *
+ * installMergeDriver:
+ *  1. Copy the esbuild bundle to `~/.co-engram/merge-driver.cjs` (version-checked).
+ *  2. Write `[merge "co-engram"]` block into the repo's `.git/config`.
+ *  3. Append the merge=co-engram entry to `.gitattributes` (idempotent).
+ *
+ * uninstallMergeDriver (spec §8.8):
+ *  - Removes `merge.co-engram.*` keys from `.git/config`.
+ *  - DOES NOT remove .gitattributes entries (committed; affects whole team).
+ *  - DOES NOT remove ~/.co-engram/merge-driver.cjs (shared across repos).
+ *    Use uninstallGlobalBundle() for that.
+ *
+ * @module @co-engram-core/merge
+ */
+import { copyFileSync, existsSync, readFileSync, appendFileSync, mkdirSync, unlinkSync, } from "node:fs";
+import { execSync } from "node:child_process";
+import { join, dirname } from "node:path";
+import { homedir } from "node:os";
+import { DRIVER_BUNDLE_VERSION } from "./version.js";
+export const GITATTRIBUTES_ENTRY = `# co-engram structured merge driver
+**/*.md            merge=co-engram
+synapses/**/*.yaml merge=co-engram
+`;
+const BUNDLE_RELATIVE_PATH = ".co-engram/merge-driver.cjs";
+const VERSION_PREFIX = "// co-engram-merge-driver v";
+function readInstalledVersion(bundlePath) {
+    if (!existsSync(bundlePath))
+        return null;
+    try {
+        const firstLine = readFileSync(bundlePath, "utf8").split("\n")[0] ?? "";
+        if (!firstLine.startsWith(VERSION_PREFIX))
+            return null;
+        return firstLine.slice(VERSION_PREFIX.length).trim();
+    }
+    catch {
+        return null;
+    }
+}
+export function installMergeDriver(params) {
+    const { repoRoot, bundleSourcePath } = params;
+    // 1. Bundle copy (version-gated)
+    const home = homedir();
+    const bundleDest = join(home, BUNDLE_RELATIVE_PATH);
+    let bundleUpgraded = false;
+    const installed = readInstalledVersion(bundleDest);
+    if (installed !== DRIVER_BUNDLE_VERSION) {
+        mkdirSync(dirname(bundleDest), { recursive: true });
+        copyFileSync(bundleSourcePath, bundleDest);
+        bundleUpgraded = true;
+    }
+    // 2. .git/config — register merge driver
+    execSync('git config merge.co-engram.name "co-engram structured merge"', {
+        cwd: repoRoot,
+    });
+    execSync(`git config merge.co-engram.driver "node ${bundleDest} %O %A %B %L %P"`, { cwd: repoRoot });
+    // 3. .gitattributes (idempotent — only append if the marker is missing)
+    const attrsPath = join(repoRoot, ".gitattributes");
+    const existing = existsSync(attrsPath) ? readFileSync(attrsPath, "utf8") : "";
+    let gitattributesUpdated = false;
+    if (!existing.includes("merge=co-engram")) {
+        appendFileSync(attrsPath, GITATTRIBUTES_ENTRY, "utf8");
+        gitattributesUpdated = true;
+    }
+    return {
+        bundlePath: bundleDest,
+        bundleUpgraded,
+        gitConfigWritten: true,
+        gitattributesUpdated,
+    };
+}
+/**
+ * Read the current onboard status for diagnostic / `co-engram git status` use.
+ */
+export function getOnboardStatus(params) {
+    const { repoRoot } = params;
+    const home = homedir();
+    const bundleDest = join(home, BUNDLE_RELATIVE_PATH);
+    const installedVersion = readInstalledVersion(bundleDest);
+    let gitConfigPresent = false;
+    try {
+        execSync("git config merge.co-engram.name", {
+            cwd: repoRoot,
+            stdio: "pipe",
+        });
+        gitConfigPresent = true;
+    }
+    catch {
+        gitConfigPresent = false;
+    }
+    const attrsPath = join(repoRoot, ".gitattributes");
+    const existing = existsSync(attrsPath) ? readFileSync(attrsPath, "utf8") : "";
+    const gitattributesPresent = existing.includes("merge=co-engram");
+    return {
+        bundleInstalled: installedVersion === DRIVER_BUNDLE_VERSION,
+        installedVersion,
+        gitConfigPresent,
+        gitattributesPresent,
+        bundlePath: bundleDest,
+    };
+}
+/**
+ * Uninstall merge driver from the repo (spec §8.8).
+ *
+ * Removes .git/config merge.co-engram.* keys. Does NOT touch:
+ *   - .gitattributes (committed; affects whole team — user decides)
+ *   - ~/.co-engram/merge-driver.cjs (shared across repos — use uninstallGlobalBundle)
+ */
+export function uninstallMergeDriver(params) {
+    const { repoRoot } = params;
+    let gitConfigRemoved = false;
+    try {
+        execSync("git config --remove-section merge.co-engram", {
+            cwd: repoRoot,
+            stdio: "pipe",
+        });
+        gitConfigRemoved = true;
+    }
+    catch {
+        // Section already absent — nothing to remove.
+        gitConfigRemoved = false;
+    }
+    return { gitConfigRemoved, bundleRemoved: false };
+}
+/**
+ * Remove the global bundle (~/.co-engram/merge-driver.cjs).
+ * Spec §8.8: explicit `co-engram git uninstall --global` only.
+ */
+export function uninstallGlobalBundle() {
+    const home = homedir();
+    const bundleDest = join(home, BUNDLE_RELATIVE_PATH);
+    if (!existsSync(bundleDest))
+        return { bundleRemoved: false };
+    try {
+        unlinkSync(bundleDest);
+        return { bundleRemoved: true };
+    }
+    catch {
+        return { bundleRemoved: false };
+    }
+}
+//# sourceMappingURL=onboard.js.map

package/dist/merge/onboard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"onboard.js","sourceRoot":"","sources":["../../src/merge/onboard.ts"],"names":[],"mappings":"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"}