@ibgib/vcs-gib 0.0.6

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

@@ -0,0 +1,202 @@
+/**
+ * @module checkout-cmd
+ * 
+ * Command handler for `vcs checkout <branchName>`.
+ * Switches activeBranch in B2tFSIndexIbGib_V1 in localSpace and projects branch snapshot onto worktree path.
+ */
+
+import path from 'node:path';
+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 { bootstrapVcsMetaspace } from '../../bootstrap/node-bootstrap.mjs';
+import { B2tFSBranchIbGib_V1 } from '../../engine/branch/branch-types.mjs';
+import { getB2tFSBranchSpaceName } from '../../engine/branch/branch-helper.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 = `[checkout-cmd]`;
+const logalot = GLOBAL_LOG_A_LOT;
+
+export interface CheckoutCmdOpts {
+    branchName?: string;
+    targetDir?: string;
+    vcsFolderName?: string;
+    quiet?: boolean;
+}
+
+export interface CheckoutCmdResult {
+    previousBranch: string;
+    currentBranch: string;
+    branchAddr: string;
+    rootItemAddr: string;
+    worktreePath: string;
+}
+
+export async function executeCheckoutCmd({
+    branchName,
+    targetDir = process.cwd(),
+    vcsFolderName = '.vcsgib',
+    quiet = false,
+}: CheckoutCmdOpts = {}): Promise<CheckoutCmdResult> {
+    const lc = `${lcFile}[${executeCheckoutCmd.name}]`;
+    try {
+        if (logalot) {
+            console.log(`${lc} starting... (I: 3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c)`);
+        }
+
+        const trimmedBranchName = branchName?.trim();
+        if (!trimmedBranchName) {
+            throw new Error(`Branch name is required for checkout (E: 4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d)`);
+        }
+
+        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: 5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e)`);
+        }
+
+        // 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: 6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f)`);
+        }
+
+        const previousBranch = indexIbGib.data?.activeBranch || 'main';
+
+        // 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);
+                }
+            }
+        }
+
+        // Find target branch node
+        const targetBranchIbGib = branchIbGibs.find(
+            (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,
+            vcsPath,
+            branchName: trimmedBranchName,
+        });
+        const targetBranchSpace = targetBranchSpaceRes.space;
+
+        await putInSpace({ space: targetBranchSpace, ibGib: targetBranchIbGib });
+
+        // Update activeBranch in B2tFSIndexIbGib_V1 in targetBranchSpace and localSpace
+        const updatedIndex = await updateB2tFSIndexIbGib({
+            space: targetBranchSpace,
+            metaspace,
+            indexIbGib,
+            dataToUpdate: {
+                activeBranch: trimmedBranchName,
+                activeSpaceId: getB2tFSBranchSpaceName(trimmedBranchName),
+                mySpaceId: targetBranchSpaceRes.spaceId,
+            },
+            vcsPath,
+        });
+
+        if (localSpace !== targetBranchSpace) {
+            await putInSpace({ space: localSpace, ibGib: updatedIndex });
+        }
+
+        // 4. Project branch snapshot onto worktree subfolder:
+        //    'main' -> repoRoot
+        //    other branches -> repoRoot/b/<branch_name>/
+        const isDefaultBranch = trimmedBranchName === 'main';
+        const worktreePath = isDefaultBranch
+            ? repoRoot
+            : path.join(repoRoot, 'b', trimmedBranchName);
+
+        await fs.mkdir(worktreePath, { recursive: true });
+
+        // Retrieve root item and project child items via writeB2tFSItemToFS
+        const rootItem = await getIbGibWithMetaspaceFallback({
+            addr: rootItemAddr,
+            space: targetBranchSpace,
+            metaspace,
+        }) 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,
+                    space: targetBranchSpace,
+                    metaspace,
+                }) as B2tFSItemIbGib_V1;
+
+                if (childItem) {
+                    await writeB2tFSItemToFS({
+                        item: childItem,
+                        destPath: worktreePath,
+                        space: targetBranchSpace,
+                        metaspace,
+                    });
+                }
+            }
+        }
+
+        if (!quiet) {
+            console.log(`Switched to branch '${trimmedBranchName}' (I: 9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c)`);
+            console.log(`  Worktree projection: ${worktreePath}`);
+        }
+
+        return {
+            previousBranch,
+            currentBranch: trimmedBranchName,
+            branchAddr: targetBranchAddr,
+            rootItemAddr,
+            worktreePath,
+        };
+    } catch (error) {
+        console.error(`${lc} ${extractErrorMsg(error)} (E: 0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d)`);
+        throw error;
+    } finally {
+        if (logalot) {
+            console.log(`${lc} complete. (I: 1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e)`);
+        }
+    }
+}

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

@@ -0,0 +1,421 @@
+/**
+ * @module commit-cmd
+ * 
+ * Command handler for `vcs commit -m "message"`.
+ * Validates staged items, evolves the B2tFS root folder item graph in localSpace,
+ * creates a CommentIbGib_V1 commit comment node, advances active B2tFSBranchIbGib_V1 pointer,
+ * clears staged items in B2tFSIndexIbGib_V1, and updates read-only index projection cache.
+ */
+
+import path from 'node:path';
+import fs from 'node:fs/promises';
+import crypto from 'node:crypto';
+
+import { getUUID, extractErrorMsg, delay } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
+import { Factory_V1 } from '@ibgib/ts-gib/dist/V1/factory.mjs';
+import { ROOT } from '@ibgib/ts-gib/dist/V1/constants.mjs';
+import { getIbGibAddr } from '@ibgib/ts-gib/dist/helper.mjs';
+import { putInSpace, persistTransformResult } from '@ibgib/core-gib/dist/witness/space/space-helper.mjs';
+import { getIbGibsFromCache_fallbackToSpaces } from '@ibgib/core-gib/dist/common/other/ibgib-helper.mjs';
+import { createCommentIbGib } from '@ibgib/core-gib/dist/common/comment/comment-helper.mjs';
+import { CommentIbGib_V1 } from '@ibgib/core-gib/dist/common/comment/comment-types.mjs';
+
+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 { getB2tFSBranchSpaceName } from '../../engine/branch/branch-helper.mjs';
+import { B2tFSBranchIbGib_V1 } from '../../engine/branch/branch-types.mjs';
+import { getB2tFSIndexIbGib, updateB2tFSIndexIbGib, getSpaceQualifiedIbGibAddr } from '../../engine/index/index-helper.mjs';
+import { B2tFSStagedItemRecord } from '../../engine/index/index-types.mjs';
+import { GLOBAL_LOG_A_LOT } from '../../vcs-gib-constants.mjs';
+
+const lcFile = `[commit-cmd]`;
+const logalot = GLOBAL_LOG_A_LOT;
+
+export interface CommitCmdOpts {
+    message?: string;
+    targetDir?: string;
+    vcsFolderName?: string;
+    quiet?: boolean;
+}
+
+export interface CommitCmdResult {
+    commitAddr: string;
+    commentAddr: string;
+    branchName: string;
+    committedPaths: string[];
+    rootItemAddr: string;
+}
+
+export async function executeCommitCmd({
+    message = '',
+    targetDir = process.cwd(),
+    vcsFolderName = '.vcsgib',
+    quiet = false,
+}: CommitCmdOpts = {}): Promise<CommitCmdResult> {
+    const lc = `${lcFile}[${executeCommitCmd.name}]`;
+
+    try {
+        if (logalot) {
+            console.log(`${lc} starting executeCommitCmd (I: 9a8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d)`);
+        }
+
+        const absTargetDir = path.resolve(targetDir);
+
+        const { metaspace, localSpace, vcsPath, repoRoot } = 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: 1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d)`);
+        }
+
+        // Validate message
+        if (!message || message.trim().length === 0) {
+            throw new Error(`Commit message is required (E: 2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e)`);
+        }
+
+        // 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: 3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f)`);
+        }
+
+        const branchName = indexIbGib.data?.activeBranch || 'main';
+
+        // Target active branch space b2s_<activeBranch>
+        const { space: activeSpace } = await getOrCreateBranchSpace({
+            metaspace,
+            vcsPath,
+            branchName,
+        });
+
+        // Validate staged items
+        const stagedPathsMap = indexIbGib.data?.stagedPaths || {};
+        const stagedAddrs = indexIbGib.data?.staged_item || [];
+        const committedPaths = Object.keys(stagedPathsMap);
+
+        if (committedPaths.length === 0 || stagedAddrs.length === 0) {
+            throw new Error(`Nothing to commit (no staged items) (E: 4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a)`);
+        }
+
+        // Fetch active branch node from activeSpace
+        const branchAddrs = [
+            ...(indexIbGib.rel8ns?.branch || []),
+            ...(indexIbGib.rel8ns?.branch_tjp || []),
+        ];
+
+        let currentBranchIbGib: B2tFSBranchIbGib_V1 | undefined;
+        let currentBranchAddr: string | undefined;
+
+        if (branchAddrs.length > 0) {
+            let branchIbGibs: B2tFSBranchIbGib_V1[] = [];
+            for (const bAddr of branchAddrs) {
+                const bIbGib = await getIbGibWithMetaspaceFallback({
+                    addr: bAddr,
+                    space: activeSpace,
+                    metaspace,
+                });
+                if (bIbGib) {
+                    branchIbGibs.push(bIbGib as B2tFSBranchIbGib_V1);
+                }
+            }
+
+            currentBranchIbGib = branchIbGibs.find(
+                (b) => (b as B2tFSBranchIbGib_V1)?.data?.name === branchName,
+            ) as B2tFSBranchIbGib_V1 || (branchIbGibs.at(0) as B2tFSBranchIbGib_V1);
+
+            if (currentBranchIbGib) {
+                currentBranchAddr = getIbGibAddr({ ibGib: currentBranchIbGib });
+            }
+        }
+
+        const currentRootAddr = currentBranchIbGib?.rel8ns?.b2tfs_item?.at(0);
+
+        // 1. Create CommentIbGib_V1 commit comment node in activeSpace
+        const commentRes = await createCommentIbGib({
+            text: message.trim(),
+            saveInSpace: true,
+            space: activeSpace,
+        });
+        const commentIbGib = commentRes.newIbGib as CommentIbGib_V1;
+        const commentAddr = getIbGibAddr({ ibGib: commentIbGib });
+        await metaspace.registerNewIbGib({ ibGib: commentIbGib, space: activeSpace });
+
+        // 2. Evolve root folder item graph with staged items in activeSpace
+        const repoName = path.basename(repoRoot) || 'root';
+        const { newRootAddr } = await commitCmd_buildEvolvedRootItem({
+            currentRootAddr,
+            stagedPathsMap,
+            space: activeSpace,
+            metaspace,
+            repoName,
+        });
+
+        // 3. Advance B2tFSBranchIbGib_V1 node inside activeSpace
+        const branchUuid = currentBranchIbGib?.data?.uuid || (await getUUID());
+        const newBranchRes = await Factory_V1.firstGen({
+            parentIbGib: currentBranchIbGib || ROOT,
+            ib: `b2tfs_branch ${branchName} v1 ${branchUuid}`,
+            data: {
+                ...(currentBranchIbGib?.data || {}),
+                name: branchName,
+                uuid: branchUuid,
+                classname: 'B2tFSBranchIbGib_V1',
+                committedAt: new Date().toISOString(),
+            },
+            rel8ns: {
+                b2tfs_item: [newRootAddr],
+                comment: [commentAddr],
+            },
+        });
+
+        const newBranchIbGib = newBranchRes.newIbGib as B2tFSBranchIbGib_V1;
+        const newBranchAddr = getIbGibAddr({ ibGib: newBranchIbGib });
+        await persistTransformResult({ resTransform: newBranchRes, space: activeSpace });
+        await metaspace.registerNewIbGib({ ibGib: newBranchIbGib, space: activeSpace });
+
+        const sqBranchAddr = getSpaceQualifiedIbGibAddr({
+            spaceId: activeSpace.data?.spaceSubPath || activeSpace.data?.name || getB2tFSBranchSpaceName(branchName),
+            ibGibAddr: newBranchAddr,
+        });
+
+        // 4. Update B2tFSIndexIbGib_V1 in activeSpace & localSpace
+        const updatedIndex = await updateB2tFSIndexIbGib({
+            space: activeSpace,
+            metaspace,
+            indexIbGib,
+            dataToUpdate: {
+                stagedPaths: {},
+                staged_item: [],
+            },
+            rel8nsToUpdate: {
+                branch: [sqBranchAddr],
+                branch_tjp: [sqBranchAddr],
+            },
+            vcsPath,
+        });
+
+        if (localSpace !== activeSpace) {
+            await putInSpace({ space: localSpace, ibGib: updatedIndex });
+        }
+
+        if (!quiet) {
+            const shortGib = newBranchIbGib.gib ? newBranchIbGib.gib.slice(0, 7) : 'commit';
+            console.log(`[${branchName} ${shortGib}] ${message.trim()} (I: 5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b)`);
+            console.log(` ${committedPaths.length} file(s) changed`);
+        }
+
+        return {
+            commitAddr: newBranchAddr,
+            commentAddr,
+            branchName,
+            committedPaths,
+            rootItemAddr: newRootAddr,
+        };
+    } catch (error) {
+        console.error(`${lc} ${extractErrorMsg(error)} (E: 6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c)`);
+        throw error;
+    } finally {
+        await delay(50);
+        if (logalot) {
+            console.log(`${lc} complete. (I: 7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d)`);
+        }
+    }
+}
+
+// #region commitCmd_buildEvolvedRootItem
+async function commitCmd_buildEvolvedRootItem({
+    currentRootAddr,
+    stagedPathsMap,
+    space,
+    metaspace,
+    repoName,
+}: {
+    currentRootAddr?: string;
+    stagedPathsMap: { [relPath: string]: B2tFSStagedItemRecord };
+    space: any;
+    metaspace: any;
+    repoName: string;
+}): Promise<{ newRootItem: B2tFSItemIbGib_V1; newRootAddr: string }> {
+    const itemsByRelPath = new Map<string, { itemAddr: string; fsType: 'file' | 'folder' }>();
+
+    if (currentRootAddr) {
+        const currentRootItem = await getIbGibWithMetaspaceFallback({
+            addr: currentRootAddr,
+            space,
+            metaspace,
+        }) as B2tFSItemIbGib_V1;
+
+        if (currentRootItem) {
+            await commitCmd_walkBranchGraph({
+                item: currentRootItem,
+                space,
+                metaspace,
+                currentRelPath: '',
+                outMap: itemsByRelPath,
+            });
+        }
+    }
+
+    // Overlay staged items
+    for (const [relPath, stagedRec] of Object.entries(stagedPathsMap)) {
+        itemsByRelPath.set(relPath, {
+            itemAddr: stagedRec.itemAddr,
+            fsType: stagedRec.fsType || 'file',
+        });
+    }
+
+    // Ensure parent folder entries exist for all items
+    const allRelPaths = Array.from(itemsByRelPath.keys());
+    for (const relPath of allRelPaths) {
+        const parts = relPath.split('/');
+        parts.pop(); // Remove file/folder name to get parent path
+        let currentFolderRel = '';
+        for (const part of parts) {
+            currentFolderRel = currentFolderRel ? `${currentFolderRel}/${part}` : part;
+            if (!itemsByRelPath.has(currentFolderRel)) {
+                itemsByRelPath.set(currentFolderRel, { itemAddr: '', fsType: 'folder' });
+            }
+        }
+    }
+
+    // Collect all folder paths (including root '')
+    const folderPathsSet = new Set<string>();
+    folderPathsSet.add('');
+    for (const [relPath, itemRec] of itemsByRelPath.entries()) {
+        if (itemRec.fsType === 'folder' || relPath === '') {
+            folderPathsSet.add(relPath);
+        }
+    }
+
+    // Sort folders deepest path first so children folders are built before parents
+    const sortedFolders = Array.from(folderPathsSet).sort((a, b) => {
+        const depthA = a ? a.split('/').length : 0;
+        const depthB = b ? b.split('/').length : 0;
+        return depthB - depthA;
+    });
+
+    const createdFolderAddrs = new Map<string, string>();
+    let rootFolderItem: B2tFSItemIbGib_V1 | undefined;
+    let rootFolderAddr: string = '';
+
+    for (const folderRelPath of sortedFolders) {
+        const childAddrs: string[] = [];
+        for (const [itemRelPath, itemRec] of itemsByRelPath.entries()) {
+            if (!itemRelPath || itemRelPath === folderRelPath) {
+                continue;
+            }
+            const parentRelPath = commitCmd_getParentRelPath(itemRelPath);
+            if (parentRelPath === folderRelPath) {
+                if (itemRec.fsType === 'folder') {
+                    const folderAddr = createdFolderAddrs.get(itemRelPath);
+                    if (folderAddr && !childAddrs.includes(folderAddr)) {
+                        childAddrs.push(folderAddr);
+                    }
+                } else {
+                    if (itemRec.itemAddr && !childAddrs.includes(itemRec.itemAddr)) {
+                        childAddrs.push(itemRec.itemAddr);
+                    }
+                }
+            }
+        }
+
+        const folderName = folderRelPath ? path.basename(folderRelPath) : repoName;
+        const diffTxId = await getUUID();
+        const nameHash = crypto.createHash('sha256').update(folderName).digest('hex');
+
+        const rel8ns: Record<string, string[]> = {};
+        if (childAddrs.length > 0) {
+            rel8ns[B2TFS_CHILD_ITEM_REL8N_NAME] = childAddrs;
+        }
+
+        const folderRes = await Factory_V1.firstGen({
+            parentIbGib: ROOT,
+            ib: getB2tFSItemIb('folder', folderName, nameHash),
+            data: {
+                name: folderName,
+                nameHash,
+                fsType: 'folder',
+                diffTransactionId: diffTxId,
+                uuid: await getUUID(),
+                classname: 'B2tFSItemIbGib_V1',
+            },
+            rel8ns,
+        });
+
+        const folderItem = folderRes.newIbGib as B2tFSItemIbGib_V1;
+        const folderAddr = getIbGibAddr({ ibGib: folderItem });
+        await persistTransformResult({ resTransform: folderRes, space });
+        await metaspace.registerNewIbGib({ ibGib: folderItem, space });
+
+        createdFolderAddrs.set(folderRelPath, folderAddr);
+
+        if (folderRelPath === '') {
+            rootFolderItem = folderItem;
+            rootFolderAddr = folderAddr;
+        }
+    }
+
+    return { newRootItem: rootFolderItem!, newRootAddr: rootFolderAddr };
+}
+
+function commitCmd_getParentRelPath(relPath: string): string {
+    const parts = relPath.split('/');
+    parts.pop();
+    return parts.join('/');
+}
+
+async function commitCmd_walkBranchGraph({
+    item,
+    space,
+    metaspace,
+    currentRelPath,
+    outMap,
+}: {
+    item: B2tFSItemIbGib_V1;
+    space: any;
+    metaspace?: any;
+    currentRelPath: string;
+    outMap: Map<string, { itemAddr: string; fsType: 'file' | 'folder' }>;
+}): Promise<void> {
+    if (!item || !item.data) { return; }
+
+    const { fsType } = item.data;
+    const itemAddr = getIbGibAddr({ ibGib: item });
+
+    if (currentRelPath) {
+        outMap.set(currentRelPath, { itemAddr, fsType });
+    }
+
+    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 commitCmd_walkBranchGraph({
+                    item: childItem,
+                    space,
+                    metaspace,
+                    currentRelPath: childRelPath,
+                    outMap,
+                });
+            }
+        }
+    }
+}
+// #endregion commitCmd_buildEvolvedRootItem