@ibgib/vcs-gib 0.0.21 → 0.0.26

package/src/cli/commands/merge-cmd.mts

@@ -2,8 +2,16 @@
  * @module merge-cmd
  *
  * Command handler for `vcs merge <branchName>`.
- * Merges target branch into active branch using SyncSagaCoordinator sync and 3-way graft merge strategy.
- * Projects merged branch snapshot onto active branch physical worktree path.
+ * Merges the incoming branch into the base (active/current) branch using
+ * SyncSagaCoordinator sync and 3-way graft merge strategy.
+ * Projects merged branch snapshot onto the base branch physical worktree path.
+ *
+ * ## Terminology (matches standard git usage)
+ *
+ * * **base** branch / space — the branch currently checked out, the one being
+ *   merged INTO (analogous to `ours` / `HEAD` in git)
+ * * **incoming** branch / space — the branch whose changes are being merged IN
+ *   (analogous to `theirs` / the topic branch in git)
  */
 
 import path from 'node:path';
@@ -11,7 +19,8 @@ import fs from 'node:fs/promises';
 
 import { clone, extractErrorMsg } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
 import { getIbGibAddr } from '@ibgib/ts-gib/dist/helper.mjs';
-import { putInSpace, getLatestAddrs, } from '@ibgib/core-gib/dist/witness/space/space-helper.mjs';
+import { putInSpace, getLatestAddrs, persistTransformResult, registerNewIbGib } from '@ibgib/core-gib/dist/witness/space/space-helper.mjs';
+import { rel8 } from '@ibgib/ts-gib/dist/V1/transforms/rel8.mjs';
 import { SyncSagaCoordinator } from '@ibgib/core-gib/dist/sync/sync-saga-coordinator.mjs';
 import { SyncPeerInnerspace_V1 } from '@ibgib/core-gib/dist/sync/sync-peer/sync-peer-innerspace/sync-peer-innerspace-v1.mjs';
 import { SYNC_PEER_INNERSPACE_DEFAULT_DATA_V1 } from '@ibgib/core-gib/dist/sync/sync-peer/sync-peer-innerspace/sync-peer-innerspace-constants.mjs';
@@ -23,43 +32,52 @@ import { bootstrapVcsMetaspace } from '../../bootstrap/node-bootstrap.mjs';
 import { B2tFSBranchIbGib_V1 } from '../../engine/branch/branch-types.mjs';
 import { getOrCreateBranchSpace } from '../../engine/branch/branch-space-helper.mjs';
 import { B2tFSItemIbGib_V1, B2TFS_CHILD_ITEM_REL8N_NAME } from '../../engine/item/item-types.mjs';
-import { writeB2tFSItemToFS, getIbGibWithMetaspaceFallback } from '../../engine/item/item-helper.mjs';
+import { writeB2tFSItemToFS, getIbGibWithMetaspaceFallback, reifyB2tFSHierarchy } from '../../engine/item/item-helper.mjs';
 import { getB2tFSIndexIbGib, updateB2tFSIndexIbGib } from '../../engine/index/index-helper.mjs';
 import { GLOBAL_LOG_A_LOT } from '../../vcs-gib-constants.mjs';
+import { logBranchState, logItemState, logCheckpoint, logAddr, logAddrs } from '../../test/test-helpers.mjs';
+
 
 const lcFile = `[merge-cmd]`;
 const logalot = GLOBAL_LOG_A_LOT;
 
 export interface MergeCmdOpts {
-    targetBranchName?: string;
+    /** The incoming branch name — the branch whose changes will be merged in. */
+    incomingBranchName?: string;
     targetDir?: string;
     vcsFolderName?: string;
     quiet?: boolean;
+    /** When true, emit diagnostic checkpoint logging (useful in tests). */
+    diagLog?: boolean;
 }
 
 export interface MergeCmdResult {
-    activeBranch: string;
-    targetBranch: string;
-    activeSpaceId: string;
-    targetSpaceId: string;
+    /** The base (current/active) branch name — merged into. */
+    baseBranch: string;
+    /** The incoming branch name — merged from. */
+    incomingBranch: string;
+    baseSpaceId: string;
+    incomingSpaceId: string;
     mergedBranchAddr?: string;
     worktreePath: string;
 }
 
 export async function executeMergeCmd({
-    targetBranchName,
+    incomingBranchName,
     targetDir = process.cwd(),
     vcsFolderName = '.vcsgib',
     quiet = false,
+    diagLog = false,
 }: MergeCmdOpts = {}): Promise<MergeCmdResult> {
     const lc = `${lcFile}[${executeMergeCmd.name}]`;
+    const diag = (label: string) => { if (diagLog) logCheckpoint(`merge-cmd: ${label}`); };
     try {
         if (logalot) {
             console.log(`${lc} starting... (I: 4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f)`);
         }
 
-        const trimmedTargetBranch = targetBranchName?.trim();
-        if (!trimmedTargetBranch) {
+        const trimmedIncomingBranch = incomingBranchName?.trim();
+        if (!trimmedIncomingBranch) {
             throw new Error(`Branch name is required for merge (E: 5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a)`);
         }
 
@@ -83,10 +101,10 @@ export async function executeMergeCmd({
             throw new Error(`Repository index B2tFSIndexIbGib_V1 not found in localSpace (E: 7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c)`);
         }
 
-        const activeBranchName = indexIbGib.data?.activeBranch || 'main';
+        const baseBranchName = indexIbGib.data?.activeBranch || 'main';
 
-        if (activeBranchName === trimmedTargetBranch) {
-            throw new Error(`Cannot merge branch '${trimmedTargetBranch}' into itself (E: 8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d)`);
+        if (baseBranchName === trimmedIncomingBranch) {
+            throw new Error(`Cannot merge branch '${trimmedIncomingBranch}' into itself (E: 8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d)`);
         }
 
         // 2. Fetch all registered branch ibgibs
@@ -109,72 +127,79 @@ export async function executeMergeCmd({
             }
         }
 
-        // Resolve active branch node & target branch node
-        const activeBranchIbGib = branchIbGibs.findLast(
-            (b) => b?.data?.name === activeBranchName,
+        // Resolve base branch node & incoming branch node
+        const baseBranchIbGib = branchIbGibs.findLast(
+            (b) => b?.data?.name === baseBranchName,
         );
-        if (!activeBranchIbGib) {
-            throw new Error(`Active branch '${activeBranchName}' not found in repository (E: 9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e)`);
+        if (!baseBranchIbGib) {
+            throw new Error(`Base branch '${baseBranchName}' not found in repository (E: 9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e)`);
         }
 
-        const targetBranchIbGib = branchIbGibs.findLast(
-            (b) => b?.data?.name === trimmedTargetBranch,
+        const incomingBranchIbGib = branchIbGibs.findLast(
+            (b) => b?.data?.name === trimmedIncomingBranch,
         );
 
-        if (!targetBranchIbGib) {
-            throw new Error(`Branch '${trimmedTargetBranch}' does not exist (E: 0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f)`);
+        if (!incomingBranchIbGib) {
+            throw new Error(`Branch '${trimmedIncomingBranch}' does not exist (E: 0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f)`);
         }
 
-        // 3. Resolve active branch space & target branch space
-        const activeSpaceRes = await getOrCreateBranchSpace({
+        // 3. Resolve base branch space & incoming branch space
+        const baseSpaceRes = await getOrCreateBranchSpace({
             metaspace,
             vcsPath,
-            branchName: activeBranchName,
+            branchName: baseBranchName,
         });
-        const activeSpace = activeSpaceRes.space;
+        const baseSpace = baseSpaceRes.space;
 
-        const targetSpaceRes = await getOrCreateBranchSpace({
+        const incomingSpaceRes = await getOrCreateBranchSpace({
             metaspace,
             vcsPath,
-            branchName: trimmedTargetBranch,
+            branchName: trimmedIncomingBranch,
         });
-        const targetSpace = targetSpaceRes.space;
+        const incomingSpace = incomingSpaceRes.space;
 
-        await putInSpace({ space: activeSpace, ibGib: activeBranchIbGib });
-        await putInSpace({ space: targetSpace, ibGib: targetBranchIbGib });
+        await putInSpace({ space: baseSpace, ibGib: baseBranchIbGib });
+        await putInSpace({ space: incomingSpace, ibGib: incomingBranchIbGib });
 
-        // Resolve latest branch tip inside targetSpace (in case commits occurred on target branch)
-        const targetBranchTjpAddr = targetBranchIbGib.rel8ns?.tjp?.at(0) || getIbGibAddr({ ibGib: targetBranchIbGib });
-        const latestTargetBranchRes = await getLatestAddrs({ space: targetSpace, addrs: [targetBranchTjpAddr] });
-        const latestTargetBranchAddr = (latestTargetBranchRes?.data as any)?.latestAddrs?.[0] || getIbGibAddr({ ibGib: targetBranchIbGib });
+        // Resolve latest branch tip inside incomingSpace (in case commits occurred on incoming branch)
+        const incomingBranchTjpAddr = incomingBranchIbGib.rel8ns?.tjp?.at(0) || getIbGibAddr({ ibGib: incomingBranchIbGib });
+        const latestIncomingBranchRes = await getLatestAddrs({ space: incomingSpace, addrs: [incomingBranchTjpAddr] });
+        const latestIncomingBranchAddr = (latestIncomingBranchRes?.data as any)?.latestAddrs?.[0] || getIbGibAddr({ ibGib: incomingBranchIbGib });
 
-        const latestTargetBranchIbGib = (await getIbGibWithMetaspaceFallback({
-            addr: latestTargetBranchAddr,
-            space: targetSpace,
+        const latestIncomingBranchIbGib = (await getIbGibWithMetaspaceFallback({
+            addr: latestIncomingBranchAddr,
+            space: incomingSpace,
             metaspace,
-        })) as B2tFSBranchIbGib_V1 || targetBranchIbGib;
+        })) as B2tFSBranchIbGib_V1 || incomingBranchIbGib;
 
-        const targetRootAddr = latestTargetBranchIbGib.rel8ns?.b2tfs_item?.at(-1);
+        const incomingRootAddr = latestIncomingBranchIbGib.rel8ns?.b2tfs_item?.at(-1);
 
-        if (!targetRootAddr) {
-            throw new Error(`Target branch '${trimmedTargetBranch}' has no valid root item address (E: 3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e)`);
+        if (!incomingRootAddr) {
+            throw new Error(`Incoming branch '${trimmedIncomingBranch}' has no valid root item address (E: 3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e)`);
         }
-        const targetRootItem = await getIbGibWithMetaspaceFallback({
-            addr: targetRootAddr,
-            space: targetSpace,
+        const incomingRootItem = await getIbGibWithMetaspaceFallback({
+            addr: incomingRootAddr,
+            space: incomingSpace,
             metaspace,
         });
-        if (!targetRootItem) {
-            throw new Error(`Target root item '${targetRootAddr}' not found in target space (E: 4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f)`);
+        if (!incomingRootItem) {
+            throw new Error(`Incoming root item '${incomingRootAddr}' not found in incoming space (E: 4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f)`);
+        }
+
+        if (diagLog) {
+            diag('resolving branches & spaces');
+            await logBranchState({ label: 'baseBranch (main)', branchIbGib: baseBranchIbGib, space: baseSpace });
+            await logBranchState({ label: 'incomingBranch (feature-merge)', branchIbGib: incomingBranchIbGib, space: incomingSpace });
+            await logItemState({ label: 'incomingRootItem', itemIbGib: incomingRootItem, space: incomingSpace });
         }
 
-        // 4. Setup SyncPeerInnerspace and SyncSagaCoordinator syncing target branch space into active branch space
+        // 4. Setup SyncPeerInnerspace and SyncSagaCoordinator syncing incoming branch space into base branch space
         const peer = new SyncPeerInnerspace_V1(clone(SYNC_PEER_INNERSPACE_DEFAULT_DATA_V1));
         await peer.initialized;
         await peer.initializeOpts({
             localMetaspace: metaspace,
-            localSpace: targetSpace,
-            receiverSpace: activeSpace,
+            localSpace: incomingSpace,
+            receiverSpace: baseSpace,
             receiverCoordinator: new SyncSagaCoordinator(),
             receiverMetaspace: metaspace,
         });
@@ -182,31 +207,74 @@ export async function executeMergeCmd({
         const senderCoordinator = new SyncSagaCoordinator();
         const syncSaga = await senderCoordinator.sync({
             peer,
-            localSpace: targetSpace,
+            localSpace: incomingSpace,
             metaspace,
-            domainIbGibs: [targetRootItem],
+            domainIbGibs: [incomingRootItem],
             conflictStrategy: SyncConflictStrategy.optimisticWithLCS,
             graftPreference: GraftPreference.receiver,
         });
 
         await syncSaga.done;
 
-        // 5. Query activeSpace for updated active branch node & root item evolved natively by sync graft strategy
-        const activeBranchTjpAddr = activeBranchIbGib.rel8ns?.tjp?.at(0) || getIbGibAddr({ ibGib: activeBranchIbGib });
-        const latestBranchRes = await getLatestAddrs({ space: activeSpace, addrs: [activeBranchTjpAddr] });
-        const mergedBranchAddr = (latestBranchRes?.data as any)?.latestAddrs?.[0] || getIbGibAddr({ ibGib: activeBranchIbGib });
+        // 5. Reify the base branch filesystem hierarchy.
+        // After sync, any child timelines (files or subfolders) that were merged/advanced
+        // in baseSpace will have newer tips. reifyB2tFSHierarchy bubbles all updated child tips
+        // up through the folder DAG, evolving parents in-place and returning the newly reified root item.
+        const currentBaseRootItemAddr = baseBranchIbGib.rel8ns?.b2tfs_item?.at(-1);
+        if (!currentBaseRootItemAddr) {
+            throw new Error(`Base branch '${baseBranchName}' has no root item address (E: 6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d)`);
+        }
 
-        const mergedBranchIbGib = (await getIbGibWithMetaspaceFallback({
-            addr: mergedBranchAddr,
-            space: activeSpace,
+        const reifyRes = await reifyB2tFSHierarchy({
+            rootItemAddr: currentBaseRootItemAddr,
+            space: baseSpace,
             metaspace,
-        })) as B2tFSBranchIbGib_V1 || activeBranchIbGib;
+        });
+
+        const reifiedRootItem = reifyRes.reifiedRootItem;
+        const reifiedRootAddr = getIbGibAddr({ ibGib: reifiedRootItem });
+
+        if (diagLog) {
+            diag('after reification');
+            logAddr('currentBaseRootItemAddr', currentBaseRootItemAddr);
+            logAddr('reifiedRootAddr', reifiedRootAddr);
+            console.log(`[merge-cmd] reification hasChanges:`, reifyRes.hasChanges);
+            console.log(`[merge-cmd] reifiedAddrsMap:`, JSON.stringify(reifyRes.reifiedAddrsMap));
+        }
 
-        const mergedRootItemAddr = mergedBranchIbGib.rel8ns?.b2tfs_item?.at(-1);
+        // 5b. Evolve the base branch ibgib to point at the reified root item tip.
+        // The sync engine does not update branch ibgibs — branches live in
+        // their own space and are never domain ibgibs in the sync. We advance
+        // the branch pointer to the reified root item.
+        let mergedBranchAddr: string = getIbGibAddr({ ibGib: baseBranchIbGib });
+        if (reifyRes.hasChanges && reifiedRootAddr !== currentBaseRootItemAddr) {
+            if (diagLog) {
+                console.log(`[merge-cmd] Evolving base branch: root item changing from ${currentBaseRootItemAddr} -> ${reifiedRootAddr}`);
+            }
+            const resRel8Branch = await rel8({
+                src: baseBranchIbGib,
+                rel8nsToReplaceByAddr: {
+                    b2tfs_item: [{ oldAddr: currentBaseRootItemAddr, newAddr: reifiedRootAddr }],
+                },
+                dna: true,
+                nCounter: true,
+            });
+            const evolvedBranchIbGib = resRel8Branch.newIbGib;
+            await persistTransformResult({ resTransform: resRel8Branch, space: baseSpace });
+            await registerNewIbGib({ ibGib: evolvedBranchIbGib, space: baseSpace });
+            mergedBranchAddr = getIbGibAddr({ ibGib: evolvedBranchIbGib });
+            if (diagLog) {
+                console.log(`[merge-cmd] Base branch evolved to addr: ${mergedBranchAddr}`);
+            }
+        } else {
+            if (diagLog) {
+                console.log(`[merge-cmd] Base branch root item unchanged (${currentBaseRootItemAddr})`);
+            }
+        }
 
         // Update indexIbGib to reference new merged branch node
         await updateB2tFSIndexIbGib({
-            space: activeSpace,
+            space: baseSpace,
             metaspace,
             indexIbGib,
             rel8nsToUpdate: {
@@ -215,28 +283,38 @@ export async function executeMergeCmd({
             vcsPath,
         });
 
+        const mergedRootItemAddr = reifiedRootAddr;
+
+        if (diagLog) {
+            diag('projecting onto disk');
+            logAddr('mergedRootItemAddr', mergedRootItemAddr);
+        }
 
         // 6. Project merged branch snapshot files onto physical worktree disk
-        const isDefaultBranch = activeBranchName === 'main';
+        const isDefaultBranch = baseBranchName === 'main';
         const worktreePath = isDefaultBranch
             ? repoRoot
-            : path.join(repoRoot, 'b', activeBranchName);
+            : path.join(repoRoot, 'b', baseBranchName);
 
         await fs.mkdir(worktreePath, { recursive: true });
 
         if (mergedRootItemAddr) {
             const mergedRootItem = await getIbGibWithMetaspaceFallback({
                 addr: mergedRootItemAddr,
-                space: activeSpace,
+                space: baseSpace,
                 metaspace,
             }) as B2tFSItemIbGib_V1;
 
+            if (diagLog) {
+                await logItemState({ label: 'mergedRootItem to write', itemIbGib: mergedRootItem, space: baseSpace });
+            }
+
             if (mergedRootItem) {
                 if (mergedRootItem.data?.fsType === 'file') {
                     await writeB2tFSItemToFS({
                         item: mergedRootItem,
                         destPath: worktreePath,
-                        space: activeSpace,
+                        space: baseSpace,
                         metaspace,
                     });
                 } else {
@@ -244,7 +322,7 @@ export async function executeMergeCmd({
                     for (const childAddr of childAddrs) {
                         const childItem = await getIbGibWithMetaspaceFallback({
                             addr: childAddr,
-                            space: activeSpace,
+                            space: baseSpace,
                             metaspace,
                         }) as B2tFSItemIbGib_V1;
 
@@ -252,7 +330,7 @@ export async function executeMergeCmd({
                             await writeB2tFSItemToFS({
                                 item: childItem,
                                 destPath: worktreePath,
-                                space: activeSpace,
+                                space: baseSpace,
                                 metaspace,
                             });
                         }
@@ -262,16 +340,16 @@ export async function executeMergeCmd({
         }
 
         if (!quiet) {
-            console.log(`Successfully merged branch '${trimmedTargetBranch}' into '${activeBranchName}' (I: 1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a)`);
+            console.log(`Successfully merged branch '${trimmedIncomingBranch}' into '${baseBranchName}' (I: 1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a)`);
             console.log(`  Worktree projection: ${worktreePath}`);
         }
 
         return {
-            activeBranch: activeBranchName,
-            targetBranch: trimmedTargetBranch,
-            activeSpaceId: activeSpaceRes.spaceId,
-            targetSpaceId: targetSpaceRes.spaceId,
-            mergedBranchAddr: getIbGibAddr({ ibGib: mergedBranchIbGib }),
+            baseBranch: baseBranchName,
+            incomingBranch: trimmedIncomingBranch,
+            baseSpaceId: baseSpaceRes.spaceId,
+            incomingSpaceId: incomingSpaceRes.spaceId,
+            mergedBranchAddr,
             worktreePath,
         };
     } catch (error) {