@ibgib/vcs-gib 0.0.17 → 0.0.20

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,285 @@
+/**
+ * @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 { putInSpace, getLatestAddrs, } 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,

package/src/engine/item/item-helper.mts

@@ -1,6 +1,6 @@
 /**
  * @module item-helper
- * 
+ *
  * B2tFS Item Helper functions: graph diff generation, filesystem projection materialization,
  * and two-pass transform application.
  */
@@ -13,23 +13,29 @@ import { extractErrorMsg, getUUID } from '@ibgib/helper-gib/dist/helpers/utils-h
 import { Factory_V1 } from '@ibgib/ts-gib/dist/V1/factory.mjs';
 import { mut8 } from '@ibgib/ts-gib/dist/V1/transforms/mut8.mjs';
 import { rel8 } from '@ibgib/ts-gib/dist/V1/transforms/rel8.mjs';
-import { getIbGibAddr } from '@ibgib/ts-gib/dist/helper.mjs';
 import { IbGib_V1 } from '@ibgib/ts-gib/dist/V1/types.mjs';
 import { TransformResult } from '@ibgib/ts-gib/dist/types.mjs';
 import { MetaspaceService } from '@ibgib/core-gib/dist/witness/space/metaspace/metaspace-types.mjs';
 import { IbGibSpaceAny } from '@ibgib/core-gib/dist/witness/space/space-base-v1.mjs';
-import { getIbGibsFromCache_fallbackToSpaces } from '@ibgib/core-gib/dist/common/other/ibgib-helper.mjs';
-import { putInSpace, persistTransformResult, getFromSpace } from '@ibgib/core-gib/dist/witness/space/space-helper.mjs';
+import { isIbGib } from '@ibgib/core-gib/dist/common/other/ibgib-helper.mjs';
+import { persistTransformResult, getFromSpace } from '@ibgib/core-gib/dist/witness/space/space-helper.mjs';
 
+import { GLOBAL_LOG_A_LOT } from '../../vcs-gib-constants.mjs';
 import { parseSpaceQualifiedIbGibAddr } from '../index/index-helper.mjs';
 import { B2TFS_ITEM_ATOM, getB2tFSItemIb } from './item-atom-helper.mjs';
-import { GLOBAL_LOG_A_LOT } from '../../vcs-gib-constants.mjs';
 import {
-    B2tFSItemIbGib_V1, B2tFSItemData_V1, B2tFSItemRel8ns_V1, B2TFS_CHILD_ITEM_REL8N_NAME, BINARY_REL8N_NAME, B2tFSItemDiffInfo
+    B2tFSItemIbGib_V1, B2tFSItemData_V1, B2tFSItemRel8ns_V1,
+    B2TFS_CHILD_ITEM_REL8N_NAME, BINARY_REL8N_NAME, B2tFSItemDiffInfo
 } from './item-types.mjs';
 
-const lcFile = `[item-helper]`;
 const logalot = GLOBAL_LOG_A_LOT;
+const lcFile = `[item-helper]`;
+
+export function isB2tFSItemIbGib(x: any): x is B2tFSItemIbGib_V1 {
+    if (!x) { return false; }
+    if (!isIbGib(x)) { return false; }
+    return x.ib.startsWith(B2TFS_ITEM_ATOM) || x.data?.classname === 'B2tFSItemIbGib_V1';
+}
 
 export interface CreateB2tFSItemIbGibOpts {
     fsType: 'file' | 'folder';
@@ -153,7 +159,7 @@ export async function evolveB2tFSItemIbGib({
 
         const hasDataChanges = dataToUpdate && Object.keys(dataToUpdate).length > 0;
         const hasRel8nsChanges = (rel8nsToUpdate && Object.keys(rel8nsToUpdate).length > 0) ||
-                                 (rel8nsToRemove && Object.keys(rel8nsToRemove).length > 0);
+            (rel8nsToRemove && Object.keys(rel8nsToRemove).length > 0);
 
         // If neither data nor rel8ns explicitly specified, update diffTransactionId to evolve timeline
         const patchData: Partial<B2tFSItemData_V1> = {
@@ -166,7 +172,7 @@ export async function evolveB2tFSItemIbGib({
             src: currentItem,
             dataToAddOrPatch: patchData,
             dna: true,
-            nCounter: true,
+            nCounter: patchData.n ? false : true, // if we manually set data.n, turn nCounter off
         });
 
         currentItem = resMut8.newIbGib as B2tFSItemIbGib_V1;

package/src/engine/item/item-types.mts

@@ -1,6 +1,6 @@
 /**
  * @module item-types
- * 
+ *
  * Baseline type definitions for B2tFS filesystem item IbGibs.
  */
 
@@ -93,6 +93,7 @@ export interface B2tFSItemRel8ns_V1 extends IbGibRel8ns_V1 {
  * B2tFS Item IbGib object structure.
  */
 export interface B2tFSItemIbGib_V1 extends IbGib_V1<B2tFSItemData_V1, B2tFSItemRel8ns_V1> {
+    data: B2tFSItemData_V1;
 }
 
 /**