@ibgib/vcs-gib 0.0.17 → 0.0.18

package/src/cli/commands/{branch-checkout-cmd.respec.node.mts → branch-checkout-cmd.respec.mts}

@@ -1,6 +1,6 @@
 /**
  * @module branch-checkout-cmd.respec
- * 
+ *
  * Unit tests for `vcs branch` and `vcs checkout` command handlers & worktree projections.
  */
 
@@ -8,7 +8,8 @@ import path from 'node:path';
 import fs from 'node:fs/promises';
 
 import {
-    respecfully, ifWe, iReckon
+    respecfully, ifWe, iReckon,
+    ifWeMight
 } from '@ibgib/helper-gib/dist/respec-gib/respec-gib.mjs';
 
 import { executeInitCmd } from './init-cmd.mjs';
@@ -16,13 +17,14 @@ import { executeAddCmd } from './add-cmd.mjs';
 import { executeCommitCmd } from './commit-cmd.mjs';
 import { executeBranchCmd } from './branch-cmd.mjs';
 import { executeCheckoutCmd } from './checkout-cmd.mjs';
+import { executeMergeCmd } from './merge-cmd.mjs';
 import { executeStatusCmd } from './status-cmd.mjs';
 
 const lc = `[apps/vcs-gib/src/cli/commands/branch-checkout-cmd.respec.node.mts]`;
 
-await respecfully(lc, `vcs branch and vcs checkout Command Handlers`, async () => {
+await respecfully(lc, `vcs branch, checkout, and merge Command Handlers`, async () => {
 
-    await ifWe(lc, `lists default branch main for new repository`, async () => {
+    await ifWeMight(lc, `lists default branch main for new repository`, async () => {
         const testDir = path.join(process.cwd(), '.test_branch_checkout_1');
         const vcsFolderName = '.vcsgib_test_bc_1';
         try {
@@ -46,7 +48,7 @@ await respecfully(lc, `vcs branch and vcs checkout Command Handlers`, async () =
         }
     });
 
-    await ifWe(lc, `creates new branch from active branch root item and rejects duplicates`, async () => {
+    await ifWeMight(lc, `creates new branch from active branch root item and rejects duplicates`, async () => {
         const testDir = path.join(process.cwd(), '.test_branch_checkout_2');
         const vcsFolderName = '.vcsgib_test_bc_2';
         try {
@@ -110,7 +112,7 @@ await respecfully(lc, `vcs branch and vcs checkout Command Handlers`, async () =
         }
     });
 
-    await ifWe(lc, `switches active branch with checkout and projects branch snapshot onto worktree subfolder`, async () => {
+    await ifWeMight(lc, `switches active branch with checkout and projects branch snapshot onto worktree subfolder`, async () => {
         const testDir = path.join(process.cwd(), '.test_branch_checkout_3');
         const vcsFolderName = '.vcsgib_test_bc_3';
         try {
@@ -236,7 +238,7 @@ await respecfully(lc, `vcs branch and vcs checkout Command Handlers`, async () =
         }
     });
 
-    await ifWe(lc, `rejects checkout when branch does not exist or branchName missing`, async () => {
+    await ifWeMight(lc, `rejects checkout when branch does not exist or branchName missing`, async () => {
         const testDir = path.join(process.cwd(), '.test_branch_checkout_4');
         const vcsFolderName = '.vcsgib_test_bc_4';
         try {
@@ -278,7 +280,7 @@ await respecfully(lc, `vcs branch and vcs checkout Command Handlers`, async () =
         }
     });
 
-    await ifWe(lc, `lists branches silently on secondary branch without error noise`, async () => {
+    await ifWeMight(lc, `lists branches silently on secondary branch without error noise`, async () => {
         const testDir = path.join(process.cwd(), '.test_branch_checkout_secondary');
         const vcsFolderName = '.vcsgib_test_bc_sec';
         try {
@@ -320,7 +322,7 @@ await respecfully(lc, `vcs branch and vcs checkout Command Handlers`, async () =
         }
     });
 
-    await ifWe(lc, `branches single file-root item and projects into file-branch worktree on checkout`, async () => {
+    await ifWeMight(lc, `branches single file-root item and projects into file-branch worktree on checkout`, async () => {
         const testDir = path.join(process.cwd(), '.test_branch_checkout_file_root');
         const vcsFolderName = '.vcsgib_test_bc_file';
         try {
@@ -398,4 +400,105 @@ await respecfully(lc, `vcs branch and vcs checkout Command Handlers`, async () =
             await fs.rm(testDir, { recursive: true, force: true });
         }
     });
+
+    await ifWeMight(lc, `performs vcs merge end-to-end between main and secondary branch`, async () => {
+        const testDir = path.join(process.cwd(), '.test_vcs_merge_e2e');
+        const vcsFolderName = '.vcsgib_test_merge_e2e';
+        try {
+            await executeInitCmd({
+                targetDir: testDir,
+                vcsFolderName,
+                quiet: true,
+            });
+
+            // 1. Initial commit on main
+            const initialContent = "line 1\nline 2\nline 3";
+            await fs.writeFile(path.join(testDir, 'app.ts'), initialContent, 'utf8');
+            await executeAddCmd({
+                paths: [path.join(testDir, 'app.ts')],
+                targetDir: testDir,
+                vcsFolderName,
+                quiet: true,
+            });
+            await executeCommitCmd({
+                message: 'Initial commit on main',
+                targetDir: testDir,
+                vcsFolderName,
+                quiet: true,
+            });
+
+            // 2. Create secondary branch feature-merge
+            await executeBranchCmd({
+                branchName: 'feature-merge',
+                targetDir: testDir,
+                vcsFolderName,
+                quiet: true,
+            });
+
+            // 3. Checkout feature-merge branch and make a commit (modify line 3)
+            await executeCheckoutCmd({
+                branchName: 'feature-merge',
+                targetDir: testDir,
+                vcsFolderName,
+                quiet: true,
+            });
+            const featureWorktree = path.join(testDir, 'b', 'feature-merge');
+            const featureContent = "line 1\nline 2\nline 3 modified by secondary";
+            await fs.writeFile(path.join(featureWorktree, 'app.ts'), featureContent, 'utf8');
+            await executeAddCmd({
+                paths: [path.join(featureWorktree, 'app.ts')],
+                targetDir: testDir,
+                vcsFolderName,
+                quiet: true,
+            });
+            await executeCommitCmd({
+                message: 'Update app.ts on feature-merge',
+                targetDir: testDir,
+                vcsFolderName,
+                quiet: true,
+            });
+
+            // 4. Checkout main branch and make a commit (modify line 1)
+            await executeCheckoutCmd({
+                branchName: 'main',
+                targetDir: testDir,
+                vcsFolderName,
+                quiet: true,
+            });
+            const mainContent = "line 1 modified by main\nline 2\nline 3";
+            await fs.writeFile(path.join(testDir, 'app.ts'), mainContent, 'utf8');
+            await executeAddCmd({
+                paths: [path.join(testDir, 'app.ts')],
+                targetDir: testDir,
+                vcsFolderName,
+                quiet: true,
+            });
+            await executeCommitCmd({
+                message: 'Update app.ts on main',
+                targetDir: testDir,
+                vcsFolderName,
+                quiet: true,
+            });
+
+            // 5. Execute vcs merge feature-merge into main
+            const mergeRes = await executeMergeCmd({
+                targetBranchName: 'feature-merge',
+                targetDir: testDir,
+                vcsFolderName,
+                quiet: true,
+            });
+
+            iReckon(lc, mergeRes.activeBranch).willEqual('main');
+            iReckon(lc, mergeRes.targetBranch).willEqual('feature-merge');
+
+            // 6. Verify projected file on physical worktree disk contains merged lines
+            const mergedAppTs = await fs.readFile(path.join(testDir, 'app.ts'), 'utf8');
+            iReckon(lc, mergedAppTs).includes('line 1 modified by main');
+            iReckon(lc, mergedAppTs).includes('line 2');
+            iReckon(lc, mergedAppTs).includes('line 3 modified by secondary');
+        } finally {
+            await fs.rm(testDir, { recursive: true, force: true });
+        }
+    });
 });
+

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

@@ -124,7 +124,7 @@ export async function executeBranchCmd({
             const branches: BranchInfo[] = [];
             for (const [name, bNode] of branchMap.entries()) {
                 const addr = getIbGibAddr({ ibGib: bNode });
-                const rootItemAddr = bNode.rel8ns?.b2tfs_item?.at(0);
+                const rootItemAddr = bNode.rel8ns?.b2tfs_item?.at(-1);
                 const isActive = name === activeBranchName;
                 branches.push({
                     name,
@@ -142,6 +142,7 @@ export async function executeBranchCmd({
             }
 
             return { branches };
+
         }
 
         // CREATE BRANCH
@@ -151,7 +152,7 @@ export async function executeBranchCmd({
 
         // Find active branch root item to fork from
         const activeBranchIbGib = branchMap.get(activeBranchName) || branchIbGibs.at(0);
-        const rootItemAddr = activeBranchIbGib?.rel8ns?.b2tfs_item?.at(0);
+        const rootItemAddr = activeBranchIbGib?.rel8ns?.b2tfs_item?.at(-1);
 
         if (!rootItemAddr) {
             throw new Error(`Cannot find active branch root item to fork branch from (E: 8f7e6d5c4b3a2f1e0d9c8b7a6f5e4d3c)`);

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

@@ -11,7 +11,8 @@ import fs from 'node:fs/promises';
 import { extractErrorMsg } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
 import { getIbGibAddr } from '@ibgib/ts-gib/dist/helper.mjs';
 import { getIbGibsFromCache_fallbackToSpaces } from '@ibgib/core-gib/dist/common/other/ibgib-helper.mjs';
-import { putInSpace } from '@ibgib/core-gib/dist/witness/space/space-helper.mjs';
+import { putInSpace, getLatestAddrs } from '@ibgib/core-gib/dist/witness/space/space-helper.mjs';
+
 
 import { bootstrapVcsMetaspace } from '../../bootstrap/node-bootstrap.mjs';
 import { B2tFSBranchIbGib_V1 } from '../../engine/branch/branch-types.mjs';
@@ -100,21 +101,15 @@ export async function executeCheckoutCmd({
         }
 
         // Find target branch node
-        const targetBranchIbGib = branchIbGibs.find(
+        const targetBranchIbGib = branchIbGibs.findLast(
             (b) => b?.data?.name === trimmedBranchName,
         );
 
+
         if (!targetBranchIbGib) {
             throw new Error(`Branch '${trimmedBranchName}' does not exist (E: 7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a)`);
         }
 
-        const targetBranchAddr = getIbGibAddr({ ibGib: targetBranchIbGib });
-        const rootItemAddr = targetBranchIbGib.rel8ns?.b2tfs_item?.at(0);
-
-        if (!rootItemAddr) {
-            throw new Error(`Branch '${trimmedBranchName}' does not have a valid root item address (E: 8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b)`);
-        }
-
         // 3. Resolve target branch space b2s_<branchName>
         const targetBranchSpaceRes = await getOrCreateBranchSpace({
             metaspace,
@@ -123,6 +118,25 @@ export async function executeCheckoutCmd({
         });
         const targetBranchSpace = targetBranchSpaceRes.space;
 
+        const targetBranchAddr = getIbGibAddr({ ibGib: targetBranchIbGib });
+        const targetBranchTjpAddr = targetBranchIbGib.rel8ns?.tjp?.at(0) || targetBranchAddr;
+        const latestTargetBranchRes = await getLatestAddrs({ space: targetBranchSpace, addrs: [targetBranchTjpAddr] });
+        const latestTargetBranchAddr = (latestTargetBranchRes?.data as any)?.latestAddrs?.[0] || targetBranchAddr;
+
+
+        const latestTargetBranchIbGib = (await getIbGibWithMetaspaceFallback({
+            addr: latestTargetBranchAddr,
+            space: targetBranchSpace,
+            metaspace,
+        })) as B2tFSBranchIbGib_V1 || targetBranchIbGib;
+
+        const rootItemAddr = latestTargetBranchIbGib.rel8ns?.b2tfs_item?.at(-1);
+
+        if (!rootItemAddr) {
+            throw new Error(`Branch '${trimmedBranchName}' does not have a valid root item address (E: 8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b)`);
+        }
+
+
         await putInSpace({ space: targetBranchSpace, ibGib: targetBranchIbGib });
 
         // Update activeBranch in B2tFSIndexIbGib_V1 in targetBranchSpace and localSpace

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

@@ -129,16 +129,18 @@ export async function executeCommitCmd({
                 }
             }
 
-            currentBranchIbGib = branchIbGibs.find(
+            currentBranchIbGib = branchIbGibs.findLast(
                 (b) => (b as B2tFSBranchIbGib_V1)?.data?.name === branchName,
-            ) as B2tFSBranchIbGib_V1 || (branchIbGibs.at(0) as B2tFSBranchIbGib_V1);
+            ) as B2tFSBranchIbGib_V1 || (branchIbGibs.at(-1) as B2tFSBranchIbGib_V1);
+
 
             if (currentBranchIbGib) {
                 currentBranchAddr = getIbGibAddr({ ibGib: currentBranchIbGib });
             }
         }
 
-        const currentRootAddr = currentBranchIbGib?.rel8ns?.b2tfs_item?.at(0);
+        const currentRootAddr = currentBranchIbGib?.rel8ns?.b2tfs_item?.at(-1);
+
 
         // 1. Create CommentIbGib_V1 commit comment node in activeSpace
         const commentRes = await createCommentIbGib({

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

@@ -0,0 +1,289 @@
+/**
+ * @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.
+ */
+
+import path from 'node:path';
+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 { rel8 } from '@ibgib/ts-gib/dist/V1/transforms/rel8.mjs';
+import { putInSpace, getLatestAddrs, getFromSpace, registerNewIbGib } from '@ibgib/core-gib/dist/witness/space/space-helper.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';
+import { SyncConflictStrategy } from '@ibgib/core-gib/dist/sync/sync-constants.mjs';
+import { GraftPreference } from '@ibgib/core-gib/dist/sync/graft-info/graft-info-types.mjs';
+
+
+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 { getB2tFSIndexIbGib, updateB2tFSIndexIbGib } from '../../engine/index/index-helper.mjs';
+import { GLOBAL_LOG_A_LOT } from '../../vcs-gib-constants.mjs';
+
+const lcFile = `[merge-cmd]`;
+const logalot = GLOBAL_LOG_A_LOT;
+
+export interface MergeCmdOpts {
+    targetBranchName?: string;
+    targetDir?: string;
+    vcsFolderName?: string;
+    quiet?: boolean;
+}
+
+export interface MergeCmdResult {
+    activeBranch: string;
+    targetBranch: string;
+    activeSpaceId: string;
+    targetSpaceId: string;
+    mergedBranchAddr?: string;
+    worktreePath: string;
+}
+
+export async function executeMergeCmd({
+    targetBranchName,
+    targetDir = process.cwd(),
+    vcsFolderName = '.vcsgib',
+    quiet = false,
+}: MergeCmdOpts = {}): Promise<MergeCmdResult> {
+    const lc = `${lcFile}[${executeMergeCmd.name}]`;
+    try {
+        if (logalot) {
+            console.log(`${lc} starting... (I: 4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f)`);
+        }
+
+        const trimmedTargetBranch = targetBranchName?.trim();
+        if (!trimmedTargetBranch) {
+            throw new Error(`Branch name is required for merge (E: 5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a)`);
+        }
+
+        const absTargetDir = path.resolve(targetDir);
+
+        const { metaspace, localSpace, repoRoot, vcsPath } = await bootstrapVcsMetaspace({
+            repoPath: absTargetDir,
+            vcsFolderName,
+        });
+
+        // Verify repo exists
+        try {
+            await fs.access(vcsPath);
+        } catch {
+            throw new Error(`Not an ibgib repository (directory ${vcsPath} does not exist) (E: 6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b)`);
+        }
+
+        // 1. Fetch authoritative repository index from localSpace
+        const indexIbGib = await getB2tFSIndexIbGib({ space: localSpace, vcsPath });
+        if (!indexIbGib) {
+            throw new Error(`Repository index B2tFSIndexIbGib_V1 not found in localSpace (E: 7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c)`);
+        }
+
+        const activeBranchName = indexIbGib.data?.activeBranch || 'main';
+
+        if (activeBranchName === trimmedTargetBranch) {
+            throw new Error(`Cannot merge branch '${trimmedTargetBranch}' into itself (E: 8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d)`);
+        }
+
+        // 2. Fetch all registered branch ibgibs
+        const branchAddrs = [
+            ...(indexIbGib.rel8ns?.branch || []),
+            ...(indexIbGib.rel8ns?.branch_tjp || []),
+        ];
+
+        let branchIbGibs: B2tFSBranchIbGib_V1[] = [];
+        if (branchAddrs.length > 0) {
+            for (const bAddr of branchAddrs) {
+                const bIbGib = await getIbGibWithMetaspaceFallback({
+                    addr: bAddr,
+                    space: localSpace,
+                    metaspace,
+                });
+                if (bIbGib) {
+                    branchIbGibs.push(bIbGib as B2tFSBranchIbGib_V1);
+                }
+            }
+        }
+
+        // Resolve active branch node & target branch node
+        const activeBranchIbGib = branchIbGibs.findLast(
+            (b) => b?.data?.name === activeBranchName,
+        );
+        if (!activeBranchIbGib) {
+            throw new Error(`Active branch '${activeBranchName}' not found in repository (E: 9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e)`);
+        }
+
+        const targetBranchIbGib = branchIbGibs.findLast(
+            (b) => b?.data?.name === trimmedTargetBranch,
+        );
+
+        if (!targetBranchIbGib) {
+            throw new Error(`Branch '${trimmedTargetBranch}' does not exist (E: 0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f)`);
+        }
+
+        // 3. Resolve active branch space & target branch space
+        const activeSpaceRes = await getOrCreateBranchSpace({
+            metaspace,
+            vcsPath,
+            branchName: activeBranchName,
+        });
+        const activeSpace = activeSpaceRes.space;
+
+        const targetSpaceRes = await getOrCreateBranchSpace({
+            metaspace,
+            vcsPath,
+            branchName: trimmedTargetBranch,
+        });
+        const targetSpace = targetSpaceRes.space;
+
+        await putInSpace({ space: activeSpace, ibGib: activeBranchIbGib });
+        await putInSpace({ space: targetSpace, ibGib: targetBranchIbGib });
+
+        // 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 });
+
+        const latestTargetBranchIbGib = (await getIbGibWithMetaspaceFallback({
+            addr: latestTargetBranchAddr,
+            space: targetSpace,
+            metaspace,
+        })) as B2tFSBranchIbGib_V1 || targetBranchIbGib;
+
+        const targetRootAddr = latestTargetBranchIbGib.rel8ns?.b2tfs_item?.at(-1);
+
+        if (!targetRootAddr) {
+            throw new Error(`Target branch '${trimmedTargetBranch}' has no valid root item address (E: 3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e)`);
+        }
+        const targetRootItem = await getIbGibWithMetaspaceFallback({
+            addr: targetRootAddr,
+            space: targetSpace,
+            metaspace,
+        });
+        if (!targetRootItem) {
+            throw new Error(`Target root item '${targetRootAddr}' not found in target space (E: 4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f)`);
+        }
+
+        // 4. Setup SyncPeerInnerspace and SyncSagaCoordinator syncing target branch space into active 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,
+            receiverCoordinator: new SyncSagaCoordinator(),
+            receiverMetaspace: metaspace,
+        });
+
+        const senderCoordinator = new SyncSagaCoordinator();
+        const syncSaga = await senderCoordinator.sync({
+            peer,
+            localSpace: targetSpace,
+            metaspace,
+            domainIbGibs: [targetRootItem],
+            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 });
+
+        const mergedBranchIbGib = (await getIbGibWithMetaspaceFallback({
+            addr: mergedBranchAddr,
+            space: activeSpace,
+            metaspace,
+        })) as B2tFSBranchIbGib_V1 || activeBranchIbGib;
+
+        const mergedRootItemAddr = mergedBranchIbGib.rel8ns?.b2tfs_item?.at(-1);
+
+        // Update indexIbGib to reference new merged branch node
+        await updateB2tFSIndexIbGib({
+            space: activeSpace,
+            metaspace,
+            indexIbGib,
+            rel8nsToUpdate: {
+                branch: [mergedBranchAddr],
+            },
+            vcsPath,
+        });
+
+
+        // 6. Project merged branch snapshot files onto physical worktree disk
+        const isDefaultBranch = activeBranchName === 'main';
+        const worktreePath = isDefaultBranch
+            ? repoRoot
+            : path.join(repoRoot, 'b', activeBranchName);
+
+        await fs.mkdir(worktreePath, { recursive: true });
+
+        if (mergedRootItemAddr) {
+            const mergedRootItem = await getIbGibWithMetaspaceFallback({
+                addr: mergedRootItemAddr,
+                space: activeSpace,
+                metaspace,
+            }) as B2tFSItemIbGib_V1;
+
+            if (mergedRootItem) {
+                if (mergedRootItem.data?.fsType === 'file') {
+                    await writeB2tFSItemToFS({
+                        item: mergedRootItem,
+                        destPath: worktreePath,
+                        space: activeSpace,
+                        metaspace,
+                    });
+                } else {
+                    const childAddrs = mergedRootItem.rel8ns?.[B2TFS_CHILD_ITEM_REL8N_NAME] || [];
+                    for (const childAddr of childAddrs) {
+                        const childItem = await getIbGibWithMetaspaceFallback({
+                            addr: childAddr,
+                            space: activeSpace,
+                            metaspace,
+                        }) as B2tFSItemIbGib_V1;
+
+                        if (childItem) {
+                            await writeB2tFSItemToFS({
+                                item: childItem,
+                                destPath: worktreePath,
+                                space: activeSpace,
+                                metaspace,
+                            });
+                        }
+                    }
+                }
+            }
+        }
+
+        if (!quiet) {
+            console.log(`Successfully merged branch '${trimmedTargetBranch}' into '${activeBranchName}' (I: 1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a)`);
+            console.log(`  Worktree projection: ${worktreePath}`);
+        }
+
+        return {
+            activeBranch: activeBranchName,
+            targetBranch: trimmedTargetBranch,
+            activeSpaceId: activeSpaceRes.spaceId,
+            targetSpaceId: targetSpaceRes.spaceId,
+            mergedBranchAddr: getIbGibAddr({ ibGib: mergedBranchIbGib }),
+            worktreePath,
+        };
+    } catch (error) {
+        console.error(`${lc} ${extractErrorMsg(error)} (E: 2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b)`);
+        throw error;
+    } finally {
+        if (logalot) {
+            console.log(`${lc} complete. (I: 3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c)`);
+        }
+    }
+}

package/src/cli/vcs-cli-main.mts

@@ -17,6 +17,7 @@ import { executeCommitCmd } from './commands/commit-cmd.mjs';
 import { executeLogCmd } from './commands/log-cmd.mjs';
 import { executeBranchCmd } from './commands/branch-cmd.mjs';
 import { executeCheckoutCmd } from './commands/checkout-cmd.mjs';
+import { executeMergeCmd } from './commands/merge-cmd.mjs';
 import { executeResetCmd } from './commands/reset-cmd.mjs';
 import { executeRestoreCmd } from './commands/restore-cmd.mjs';
 import { AUTO_GENERATED_VERSION } from '../AUTO-GENERATED-version.mjs';
@@ -44,6 +45,7 @@ Commands:
   log                   Show commit logs
   branch [name]         List or create branches
   checkout <branch>     Switch to a specified branch and project worktree
+  merge <branch>        Merge specified branch into active branch
   reset [path...]       Unstage specified files from index (-a, --all for all)
   restore [path...]     Restore working tree files or unstage (--staged)
 
@@ -120,6 +122,11 @@ export async function main({
                 await executeCheckoutCmd({ branchName });
                 break;
             }
+            case VCS_SUBCOMMANDS.MERGE: {
+                const targetBranchName = parsed.positionals[0] || parsed.flags.branchName;
+                await executeMergeCmd({ targetBranchName });
+                break;
+            }
             case VCS_SUBCOMMANDS.RESET: {
                 await executeResetCmd({
                     paths: parsed.positionals,