@ibgib/vcs-gib 0.0.6 → 0.0.18

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

@@ -22,11 +22,13 @@ import { bootstrapVcsMetaspace } from '../../bootstrap/node-bootstrap.mjs';
 import { getOrCreateBranchSpace } from '../../engine/branch/branch-space-helper.mjs';
 import { getB2tFSItemIb } from '../../engine/item/item-atom-helper.mjs';
 import { B2tFSItemIbGib_V1, B2TFS_CHILD_ITEM_REL8N_NAME } from '../../engine/item/item-types.mjs';
-import { getIbGibWithMetaspaceFallback } from '../../engine/item/item-helper.mjs';
+import { getIbGibWithMetaspaceFallback, createB2tFSItemIbGib, evolveB2tFSItemIbGib } from '../../engine/item/item-helper.mjs';
 import { B2tFSBranchIbGib_V1 } from '../../engine/branch/branch-types.mjs';
 import { isPathFiltered, parseFilterFileContent, globToRegExp } from '../../engine/filter/glob-helper.mjs';
 import { getB2tFSIndexIbGib, updateB2tFSIndexIbGib } from '../../engine/index/index-helper.mjs';
 import { B2tFSStagedItemRecord } from '../../engine/index/index-types.mjs';
+import { TransformResult } from '@ibgib/ts-gib/dist/types.mjs';
+import { IbGib_V1 } from '@ibgib/ts-gib/dist/V1/types.mjs';
 import { GLOBAL_LOG_A_LOT } from '../../vcs-gib-constants.mjs';
 
 const lcFile = `[add-cmd]`;
@@ -97,7 +99,7 @@ export async function executeAddCmd({
         }
 
         // Walk active branch graph items to find committed files in snapshot
-        const committedBranchItemsMap = new Map<string, { relPath: string; fileHash?: string; fsType: 'file' | 'folder' }>();
+        const committedBranchItemsMap = new Map<string, { relPath: string; fileHash?: string; fsType: 'file' | 'folder'; item?: B2tFSItemIbGib_V1 }>();
         const branchAddrs = [
             ...(indexIbGib?.rel8ns?.branch || []),
             ...(indexIbGib?.rel8ns?.branch_tjp || []),
@@ -116,11 +118,13 @@ export async function executeAddCmd({
                 }
             }
 
-            const activeBranchIbGib = branchIbGibs.find(
+            const activeBranchIbGib = branchIbGibs.findLast(
                 (b) => (b as B2tFSBranchIbGib_V1)?.data?.name === activeBranch,
-            ) as B2tFSBranchIbGib_V1 || (branchIbGibs.at(0) as B2tFSBranchIbGib_V1);
+            ) as B2tFSBranchIbGib_V1 || (branchIbGibs.at(-1) as B2tFSBranchIbGib_V1);
+
+
+            const rootItemAddr = activeBranchIbGib?.rel8ns?.b2tfs_item?.at(-1);
 
-            const rootItemAddr = activeBranchIbGib?.rel8ns?.b2tfs_item?.at(0);
             if (rootItemAddr) {
                 const rootItem = await getIbGibWithMetaspaceFallback({
                     addr: rootItemAddr,
@@ -182,7 +186,7 @@ export async function executeAddCmd({
                         throw new Error(`No files matched glob pattern: ${relOrAbs} (E: e23d4c5f6a7b8c9d0e1f2a3b4c5d6e7f)`);
                     }
                 } else {
-                    const fullPath = path.resolve(activeWorktreeDir, relOrAbs);
+                    const fullPath = path.resolve(targetDir, relOrAbs);
                     let stat;
                     try {
                         stat = await fs.stat(fullPath);
@@ -191,6 +195,9 @@ export async function executeAddCmd({
                     }
 
                     const relPath = path.relative(activeWorktreeDir, fullPath).replace(/\\/g, '/');
+                    if (relPath.startsWith('..') || path.isAbsolute(relPath)) {
+                        throw new Error(`Path '${relOrAbs}' is outside of active worktree repository (E: 7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f)`);
+                    }
 
                     if (isPathFiltered({ relativePath: relPath, isDirectory: stat.isDirectory(), filterPatterns })) {
                         continue;
@@ -243,31 +250,36 @@ export async function executeAddCmd({
             await putInSpace({ ibGib: binIbGib, space: activeSpace });
             await metaspace.registerNewIbGib({ ibGib: binIbGib, space: activeSpace });
 
-            // 2. Create B2tFSItemIbGib_V1 candidate graph node
+            // 2. Create or Evolve B2tFSItemIbGib_V1 candidate graph node
             const fileName = path.basename(absFilePath);
-            const fileNameSansExt = path.parse(fileName).name;
-            const fileExt = path.parse(fileName).ext.replace(/^\./, '');
             const nameHash = crypto.createHash('sha256').update(fileName).digest('hex');
 
-            const itemRes = await Factory_V1.firstGen({
-                parentIbGib: ROOT,
-                ib: getB2tFSItemIb('file', fileName, nameHash),
-                data: {
-                    name: fileName,
-                    nameHash,
+            let itemRes: TransformResult<IbGib_V1>;
+            if (committedItem && committedItem.item) {
+                itemRes = await evolveB2tFSItemIbGib({
+                    existingItem: committedItem.item,
+                    dataToUpdate: {
+                        fileHash,
+                    },
+                    rel8nsToUpdate: {
+                        bin: [binAddr],
+                    },
+                });
+            } else {
+                itemRes = await createB2tFSItemIbGib({
                     fsType: 'file',
-                    fileNameSansExt,
-                    fileExt,
-                    fileHash,
-                    fileEncoding: 'utf8',
-                    diffTransactionId: await getUUID(),
-                    uuid: await getUUID(),
-                    classname: 'B2tFSItemIbGib_V1',
-                },
-                rel8ns: {
-                    bin: [binAddr],
-                },
-            });
+                    name: fileName,
+                    data: {
+                        nameHash,
+                        fileHash,
+                        fileEncoding: 'utf8',
+                    },
+                    rel8ns: {
+                        bin: [binAddr],
+                    },
+                });
+            }
+
             const itemIbGib = itemRes.newIbGib as B2tFSItemIbGib_V1;
             const itemAddr = getIbGibAddr({ ibGib: itemIbGib });
             await persistTransformResult({ resTransform: itemRes, space: activeSpace });
@@ -332,13 +344,13 @@ async function addCmd_walkBranchGraph({
     space: any;
     metaspace?: any;
     currentRelPath: string;
-    outMap: Map<string, { relPath: string; fileHash?: string; fsType: 'file' | 'folder' }>;
+    outMap: Map<string, { relPath: string; fileHash?: string; fsType: 'file' | 'folder'; item?: B2tFSItemIbGib_V1 }>;
 }): Promise<void> {
     if (!item || !item.data) { return; }
 
     const { fsType, fileHash } = item.data;
     if (currentRelPath) {
-        outMap.set(currentRelPath, { relPath: currentRelPath, fileHash, fsType });
+        outMap.set(currentRelPath, { relPath: currentRelPath, fileHash, fsType, item });
     }
 
     if (fsType === 'folder') {

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 {
@@ -319,4 +321,184 @@ await respecfully(lc, `vcs branch and vcs checkout Command Handlers`, async () =
             await fs.rm(testDir, { recursive: true, force: true });
         }
     });
+
+    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 {
+            await executeInitCmd({
+                targetDir: testDir,
+                vcsFolderName,
+                quiet: true,
+            });
+
+            // Create nested file structure src/utils/math.js and commit on main
+            const mathRelPath = 'src/utils/math.js';
+            await fs.mkdir(path.join(testDir, 'src', 'utils'), { recursive: true });
+            await fs.writeFile(path.join(testDir, mathRelPath), 'export function add(a, b) { return a + b; }', 'utf8');
+
+            await executeAddCmd({
+                paths: [mathRelPath],
+                targetDir: testDir,
+                vcsFolderName,
+                quiet: true,
+            });
+
+            await executeCommitCmd({
+                message: 'Add math.js',
+                targetDir: testDir,
+                vcsFolderName,
+                quiet: true,
+            });
+
+            // Execute branch command for single file math-opt targeting src/utils/math.js
+            const branchRes = await executeBranchCmd({
+                branchName: 'math-opt',
+                itemPath: mathRelPath,
+                targetDir: testDir,
+                vcsFolderName,
+                quiet: true,
+            });
+
+            iReckon(lc, branchRes.createdBranchName).willEqual('math-opt');
+
+            // Attempt branching uncommitted/non-existent item
+            let uncommittedErr = false;
+            try {
+                await executeBranchCmd({
+                    branchName: 'invalid-file-branch',
+                    itemPath: 'src/utils/non-existent.js',
+                    targetDir: testDir,
+                    vcsFolderName,
+                    quiet: true,
+                });
+            } catch (err: any) {
+                uncommittedErr = true;
+                iReckon(lc, err.message).includes("not found in active branch snapshot");
+            }
+            iReckon(lc, uncommittedErr).isGonnaBeTrue();
+
+            // Execute checkout command for math-opt
+            const checkoutRes = await executeCheckoutCmd({
+                branchName: 'math-opt',
+                targetDir: testDir,
+                vcsFolderName,
+                quiet: true,
+            });
+
+            const expectedWorktree = path.join(testDir, 'b', 'math-opt');
+            iReckon(lc, checkoutRes.worktreePath).willEqual(expectedWorktree);
+
+            // Verify single file projected at expectedWorktree/math.js (my-repo/b/math-opt/math.js)
+            const projectedFilePath = path.join(expectedWorktree, 'math.js');
+            const fileExists = await fs.stat(projectedFilePath).then(s => s.isFile()).catch(() => false);
+            iReckon(lc, fileExists).isGonnaBeTrue();
+
+            const fileContent = await fs.readFile(projectedFilePath, 'utf8');
+            iReckon(lc, fileContent).willEqual('export function add(a, b) { return a + b; }');
+        } finally {
+            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

@@ -18,7 +18,7 @@ import { B2tFSBranchIbGib_V1 } from '../../engine/branch/branch-types.mjs';
 import { createB2tFSBranchIbGib } from '../../engine/branch/branch-helper.mjs';
 import { getOrCreateBranchSpace } from '../../engine/branch/branch-space-helper.mjs';
 import { populateBranchSpaceFromGraph } from '../../engine/branch/branch-graph-helper.mjs';
-import { B2tFSItemIbGib_V1 } from '../../engine/item/item-types.mjs';
+import { B2tFSItemIbGib_V1, B2TFS_CHILD_ITEM_REL8N_NAME } from '../../engine/item/item-types.mjs';
 import { getIbGibWithMetaspaceFallback } from '../../engine/item/item-helper.mjs';
 import { getB2tFSIndexIbGib, updateB2tFSIndexIbGib, getSpaceQualifiedIbGibAddr } from '../../engine/index/index-helper.mjs';
 import { GLOBAL_LOG_A_LOT } from '../../vcs-gib-constants.mjs';
@@ -28,6 +28,7 @@ const logalot = GLOBAL_LOG_A_LOT;
 
 export interface BranchCmdOpts {
     branchName?: string;
+    itemPath?: string;
     targetDir?: string;
     vcsFolderName?: string;
     quiet?: boolean;
@@ -48,6 +49,7 @@ export interface BranchCmdResult {
 
 export async function executeBranchCmd({
     branchName,
+    itemPath,
     targetDir = process.cwd(),
     vcsFolderName = '.vcsgib',
     quiet = false,
@@ -122,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,
@@ -140,6 +142,7 @@ export async function executeBranchCmd({
             }
 
             return { branches };
+
         }
 
         // CREATE BRANCH
@@ -149,10 +152,10 @@ 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: 8a7b6c5d4e3f2a1b0c9d8e7f6a5b4c3d)`);
+            throw new Error(`Cannot find active branch root item to fork branch from (E: 8f7e6d5c4b3a2f1e0d9c8b7a6f5e4d3c)`);
         }
 
         const rootItem = await getIbGibWithMetaspaceFallback({
@@ -165,6 +168,25 @@ export async function executeBranchCmd({
             throw new Error(`Root item node for address '${rootItemAddr}' not found in localSpace (E: 9b8c7d6e5f4a3b2c1d0e9f8a7b6c5d4e)`);
         }
 
+        let targetRootItem: B2tFSItemIbGib_V1 = rootItem;
+        if (itemPath && itemPath.trim().length > 0) {
+            const normalizedItemPath = itemPath.trim().replace(/\\/g, '/').replace(/^\.\//, '');
+            const committedBranchItemsMap = new Map<string, B2tFSItemIbGib_V1>();
+            await executeBranchCmd_walkBranchGraphForItems({
+                item: rootItem,
+                space: activeBranchSpace,
+                metaspace,
+                currentRelPath: '',
+                outMap: committedBranchItemsMap,
+            });
+
+            const targetItemNode = committedBranchItemsMap.get(normalizedItemPath);
+            if (!targetItemNode) {
+                throw new Error(`Item '${itemPath}' not found in active branch snapshot (E: 8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c)`);
+            }
+            targetRootItem = targetItemNode;
+        }
+
         // Instantiate new branch space b2s_<newBranch>
         const { space: newBranchSpace, spaceId: newBranchSpaceId } = await getOrCreateBranchSpace({
             metaspace,
@@ -172,18 +194,18 @@ export async function executeBranchCmd({
             branchName: trimmedBranchName,
         });
 
-        // Populate new branch space from live dependency graph of rootItem
+        // Populate new branch space from live dependency graph of targetRootItem
         await populateBranchSpaceFromGraph({
             sourceSpace: activeBranchSpace,
             targetBranchSpace: newBranchSpace,
-            rootItemIbGib: rootItem,
+            rootItemIbGib: targetRootItem,
             metaspace,
         });
 
         // Create new B2tFSBranchIbGib_V1 branch node inside newBranchSpace
         const newBranchIbGib = await createB2tFSBranchIbGib({
             branchName: trimmedBranchName,
-            rootItem,
+            rootItem: targetRootItem,
             space: newBranchSpace,
             metaspace,
         });
@@ -210,7 +232,7 @@ export async function executeBranchCmd({
         });
 
         if (!quiet) {
-            console.log(`Created branch '${trimmedBranchName}' (I: 0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f)`);
+            console.log(`Created branch '${trimmedBranchName}' (I: 0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5e)`);
         }
 
         // Return updated branch list
@@ -241,3 +263,51 @@ export async function executeBranchCmd({
         }
     }
 }
+
+// #region executeBranchCmd_walkBranchGraphForItems
+async function executeBranchCmd_walkBranchGraphForItems({
+    item,
+    space,
+    metaspace,
+    currentRelPath,
+    outMap,
+}: {
+    item: B2tFSItemIbGib_V1;
+    space: any;
+    metaspace?: any;
+    currentRelPath: string;
+    outMap: Map<string, B2tFSItemIbGib_V1>;
+}): Promise<void> {
+    if (!item || !item.data) { return; }
+
+    const { fsType } = item.data;
+
+    if (currentRelPath) {
+        outMap.set(currentRelPath, item);
+    }
+
+    if (fsType === 'folder') {
+        const childAddrs = item.rel8ns?.[B2TFS_CHILD_ITEM_REL8N_NAME] || [];
+        for (const childAddr of childAddrs) {
+            const childItem = await getIbGibWithMetaspaceFallback({
+                addr: childAddr,
+                space,
+                metaspace,
+            }) as B2tFSItemIbGib_V1;
+
+            if (childItem && childItem.data) {
+                const childRelPath = currentRelPath
+                    ? `${currentRelPath}/${childItem.data.name}`
+                    : childItem.data.name;
+                await executeBranchCmd_walkBranchGraphForItems({
+                    item: childItem,
+                    space,
+                    metaspace,
+                    currentRelPath: childRelPath,
+                    outMap,
+                });
+            }
+        }
+    }
+}
+// #endregion executeBranchCmd_walkBranchGraphForItems

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';
@@ -49,7 +50,7 @@ export async function executeCheckoutCmd({
     const lc = `${lcFile}[${executeCheckoutCmd.name}]`;
     try {
         if (logalot) {
-            console.log(`${lc} starting... (I: 3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c)`);
+            console.log(`${lc} starting... (I: 3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8e)`);
         }
 
         const trimmedBranchName = branchName?.trim();
@@ -68,7 +69,7 @@ export async function executeCheckoutCmd({
         try {
             await fs.access(vcsPath);
         } catch {
-            throw new Error(`Not an ibgib repository (directory ${vcsPath} does not exist) (E: 5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e)`);
+            throw new Error(`Not an ibgib repository (directory ${vcsPath} does not exist) (E: 5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0e)`);
         }
 
         // 1. Fetch authoritative repository index from localSpace
@@ -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
@@ -152,7 +166,9 @@ export async function executeCheckoutCmd({
 
         await fs.mkdir(worktreePath, { recursive: true });
 
-        // Retrieve root item and project child items via writeB2tFSItemToFS
+        // Retrieve root item and project branch snapshot onto worktree subfolder:
+        // If rootItem is a single file, write it directly to worktreePath (my-repo/b/<branchName>/<fileName>).
+        // If rootItem is a folder, write child items into worktreePath.
         const rootItem = await getIbGibWithMetaspaceFallback({
             addr: rootItemAddr,
             space: targetBranchSpace,
@@ -160,21 +176,30 @@ export async function executeCheckoutCmd({
         }) as B2tFSItemIbGib_V1;
 
         if (rootItem) {
-            const childAddrs = rootItem.rel8ns?.[B2TFS_CHILD_ITEM_REL8N_NAME] || [];
-            for (const childAddr of childAddrs) {
-                const childItem = await getIbGibWithMetaspaceFallback({
-                    addr: childAddr,
+            if (rootItem.data?.fsType === 'file') {
+                await writeB2tFSItemToFS({
+                    item: rootItem,
+                    destPath: worktreePath,
                     space: targetBranchSpace,
                     metaspace,
-                }) as B2tFSItemIbGib_V1;
-
-                if (childItem) {
-                    await writeB2tFSItemToFS({
-                        item: childItem,
-                        destPath: worktreePath,
+                });
+            } else {
+                const childAddrs = rootItem.rel8ns?.[B2TFS_CHILD_ITEM_REL8N_NAME] || [];
+                for (const childAddr of childAddrs) {
+                    const childItem = await getIbGibWithMetaspaceFallback({
+                        addr: childAddr,
                         space: targetBranchSpace,
                         metaspace,
-                    });
+                    }) as B2tFSItemIbGib_V1;
+
+                    if (childItem) {
+                        await writeB2tFSItemToFS({
+                            item: childItem,
+                            destPath: worktreePath,
+                            space: targetBranchSpace,
+                            metaspace,
+                        });
+                    }
                 }
             }
         }