@ibgib/vcs-gib 0.0.30 → 0.0.32

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

@@ -1,705 +0,0 @@
-/**
- * @module index-helper
- * 
- * B2tFS Index Helper functions: space-qualified address formatting and branch index tracking.
- */
-
-import path from 'node:path';
-import fs from 'node:fs/promises';
-
-import { getUUID, extractErrorMsg } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
-import { ROOT } from '@ibgib/ts-gib/dist/V1/constants.mjs';
-import { Factory_V1 } from '@ibgib/ts-gib/dist/V1/factory.mjs';
-import { getIbGibAddr } from '@ibgib/ts-gib/dist/helper.mjs';
-import { getIbGibsFromCache_fallbackToSpaces } from '@ibgib/core-gib/dist/common/other/ibgib-helper.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 { putInSpace, persistTransformResult } from '@ibgib/core-gib/dist/witness/space/space-helper.mjs';
-
-import { GLOBAL_LOG_A_LOT } from '../../vcs-gib-constants.mjs';
-import { SpaceQualifiedIbGibAddr, B2tFSIndexIbGib_V1, B2tFSIndexData_V1, B2tFSIndexRel8ns_V1 } from './index-types.mjs';
-import { B2tFSBranchIbGib_V1 } from '../branch/branch-types.mjs';
-import { B2tFSItemIbGib_V1, B2TFS_CHILD_ITEM_REL8N_NAME } from '../item/item-types.mjs';
-import { getIbGibWithMetaspaceFallback, writeB2tFSItemToFS } from '../item/item-helper.mjs';
-
-const lcFile = `[index-helper]`;
-const logalot = GLOBAL_LOG_A_LOT;
-
-export const SOFT_ADDR_DATA_KEY_PREFIX = '@';
-export const SOFT_ADDR_DATA_KEY_PREFIX_SPACE_QUALIFIED = '$@';
-
-/**
- * Returns a space-qualified address string.
- * Format: `v:1^spaceId:<spaceId>^<ibGibAddr>`
- */
-export function getSpaceQualifiedIbGibAddr(
-    optsOrSpaceId: { spaceId: string; ibGibAddr: string } | string,
-    rawIbGibAddr?: string,
-): SpaceQualifiedIbGibAddr {
-    if (typeof optsOrSpaceId === 'object' && optsOrSpaceId !== null) {
-        return `v:1^spaceId:${optsOrSpaceId.spaceId}^${optsOrSpaceId.ibGibAddr}`;
-    }
-    return `v:1^spaceId:${optsOrSpaceId}^${rawIbGibAddr}`;
-}
-
-/**
- * Parses a space-qualified address string into version, spaceId, ibGibAddr, ib, and gib.
- */
-export function parseSpaceQualifiedIbGibAddr(
-    optsOrSqAddr: { spaceQualifiedAddr: string } | { sqAddr: string } | string,
-): { version: number; spaceId: string; ibGibAddr: string; ib: string; gib: string } | null {
-    let sqAddr: string | undefined;
-    if (typeof optsOrSqAddr === 'string') {
-        sqAddr = optsOrSqAddr;
-    } else if (typeof optsOrSqAddr === 'object' && optsOrSqAddr !== null) {
-        sqAddr = (optsOrSqAddr as any).spaceQualifiedAddr || (optsOrSqAddr as any).sqAddr;
-    }
-
-    if (!sqAddr || typeof sqAddr !== 'string') {
-        return null;
-    }
-
-    const match = sqAddr.match(/^v:(\d+)\^spaceId:([^\^]+)\^(.+)$/);
-    if (!match) {
-        return null;
-    }
-
-    const version = parseInt(match[1], 10);
-    const spaceId = match[2];
-    const ibGibAddr = match[3];
-
-    const lastCaretIndex = ibGibAddr.lastIndexOf('^');
-    if (lastCaretIndex === -1) {
-        return null;
-    }
-
-    const ib = ibGibAddr.substring(0, lastCaretIndex);
-    const gib = ibGibAddr.substring(lastCaretIndex + 1);
-
-    if (!ib || !gib) {
-        return null;
-    }
-
-    return {
-        version,
-        spaceId,
-        ibGibAddr,
-        ib,
-        gib,
-    };
-}
-
-/**
- * Helper to extract branch name from space-qualified address or raw atom ib string.
- */
-export function extractBranchNameFromAddr(addr: string): string | null {
-    if (!addr) {
-        return null;
-    }
-    const sq = parseSpaceQualifiedIbGibAddr(addr);
-    const ib = sq ? sq.ib : (addr.includes('^') ? addr.substring(0, addr.lastIndexOf('^')) : addr);
-    if (ib && ib.startsWith('b2tfs_branch ')) {
-        const parts = ib.split(' ');
-        if (parts.length >= 2 && parts[1]) {
-            return parts[1];
-        }
-    }
-    return null;
-}
-
-/**
- * Deduplicates branch entries by branch name and merges new branch addresses into existing addresses
- * without dropping other registered branches.
- */
-export function mergeBranchAddrs(
-    existingAddrs: string[] = [],
-    newAddrs: string[] = [],
-): string[] {
-    const map = new Map<string, string>();
-    for (const addr of existingAddrs) {
-        if (!addr) {
-            continue;
-        }
-        const bName = extractBranchNameFromAddr(addr) || addr;
-        map.set(bName, addr);
-    }
-    for (const addr of newAddrs) {
-        if (!addr) {
-            continue;
-        }
-        const bName = extractBranchNameFromAddr(addr) || addr;
-        map.set(bName, addr);
-    }
-    return Array.from(map.values());
-}
-
-/**
- * Creates a new B2tFSIndexIbGib special meta object for a space.
- */
-export async function createB2tFSIndexIbGib({
-    spaceId,
-    activeSpaceId,
-    activeBranch,
-    space,
-    metaspace,
-    branchAddr,
-}: {
-    spaceId: string;
-    activeSpaceId: string;
-    activeBranch?: string;
-    space: IbGibSpaceAny;
-    metaspace: MetaspaceService;
-    branchAddr?: string;
-}): Promise<B2tFSIndexIbGib_V1> {
-    const lc = `${lcFile}[${createB2tFSIndexIbGib.name}]`;
-    try {
-        if (logalot) {
-            console.log(`${lc} starting... (I: 3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d)`);
-        }
-
-        const uuid = await getUUID();
-        const data: B2tFSIndexData_V1 = {
-            mySpaceId: spaceId,
-            activeSpaceId,
-            activeBranch,
-            uuid,
-            classname: 'B2tFSIndexIbGib_V1',
-            '$@branch': [],
-            stagedPaths: {},
-            staged_item: [],
-        };
-
-        const rel8ns: B2tFSIndexRel8ns_V1 = {};
-        if (branchAddr) {
-            const sqBranchAddr = branchAddr.startsWith('v:1^spaceId:')
-                ? branchAddr
-                : getSpaceQualifiedIbGibAddr({
-                    spaceId: space.data?.spaceSubPath || space.data?.name || spaceId,
-                    ibGibAddr: branchAddr,
-                });
-            rel8ns.branch = [sqBranchAddr];
-            rel8ns.branch_tjp = [sqBranchAddr];
-        }
-
-        const res = await Factory_V1.firstGen({
-            parentIbGib: ROOT,
-            ib: `meta special b2tfs_index ${uuid}`,
-            data,
-            rel8ns: Object.keys(rel8ns).length > 0 ? rel8ns : undefined,
-        });
-
-        const indexIbGib = res.newIbGib as B2tFSIndexIbGib_V1;
-        await persistTransformResult({ resTransform: res, space });
-        await metaspace.registerNewIbGib({ ibGib: indexIbGib });
-
-        if (logalot) {
-            console.log(`${lc} Created index IbGib: ${indexIbGib.ib} (I: 4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e)`);
-        }
-
-        return indexIbGib;
-    } catch (error) {
-        console.error(`${lc} ${extractErrorMsg(error)} (E: 5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f)`);
-        throw error;
-    } finally {
-        if (logalot) {
-            console.log(`${lc} complete. (I: 6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a)`);
-        }
-    }
-}
-
-/**
- * Retrieves authoritative B2tFSIndexIbGib_V1 from space.
- */
-export async function getB2tFSIndexIbGib({
-    space,
-    vcsPath,
-}: {
-    space: IbGibSpaceAny;
-    vcsPath?: string;
-}): Promise<B2tFSIndexIbGib_V1 | undefined> {
-    const lc = `${lcFile}[${getB2tFSIndexIbGib.name}]`;
-    try {
-        if (logalot) {
-            console.log(`${lc} starting... (I: 7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b)`);
-        }
-
-        if (!vcsPath) {
-            return undefined;
-        }
-
-        const projPath = path.join(vcsPath, 'vcs_index_projection.json');
-        let indexAddr: string | undefined;
-        try {
-            const raw = await fs.readFile(projPath, 'utf8');
-            const parsed = JSON.parse(raw);
-            indexAddr = parsed.indexAddr;
-        } catch {
-            return undefined;
-        }
-
-        if (!indexAddr) {
-            return undefined;
-        }
-
-        const ibgibs = await getIbGibsFromCache_fallbackToSpaces({
-            addrs: [indexAddr],
-            space,
-        });
-
-        const indexIbGib = ibgibs?.at(0) as B2tFSIndexIbGib_V1;
-        return indexIbGib;
-    } catch (error) {
-        console.error(`${lc} ${extractErrorMsg(error)} (E: 8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c)`);
-        throw error;
-    } finally {
-        if (logalot) {
-            console.log(`${lc} complete. (I: 9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d)`);
-        }
-    }
-}
-
-/**
- * Updates B2tFSIndexIbGib_V1 in space and updates local projection cache.
- */
-export async function updateB2tFSIndexIbGib({
-    space,
-    metaspace,
-    indexIbGib,
-    dataToUpdate,
-    rel8nsToUpdate,
-    vcsPath,
-}: {
-    space: IbGibSpaceAny;
-    metaspace: MetaspaceService;
-    indexIbGib: B2tFSIndexIbGib_V1;
-    dataToUpdate?: Partial<B2tFSIndexData_V1>;
-    rel8nsToUpdate?: Partial<B2tFSIndexRel8ns_V1>;
-    vcsPath?: string;
-}): Promise<B2tFSIndexIbGib_V1> {
-    const lc = `${lcFile}[${updateB2tFSIndexIbGib.name}]`;
-    try {
-        if (logalot) {
-            console.log(`${lc} starting... (I: 0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e)`);
-        }
-
-        const mergedData: B2tFSIndexData_V1 = {
-            ...(indexIbGib.data || {
-                mySpaceId: space.data?.uuid || '',
-                activeSpaceId: '',
-                uuid: await getUUID(),
-            }),
-            ...dataToUpdate,
-        };
-
-        const mergedRel8ns: B2tFSIndexRel8ns_V1 = {
-            ...(indexIbGib.rel8ns || {}),
-            ...rel8nsToUpdate,
-        };
-
-        if (rel8nsToUpdate?.branch || indexIbGib.rel8ns?.branch) {
-            mergedRel8ns.branch = mergeBranchAddrs(
-                indexIbGib.rel8ns?.branch || [],
-                rel8nsToUpdate?.branch || [],
-            );
-        }
-
-        if (rel8nsToUpdate?.branch_tjp || indexIbGib.rel8ns?.branch_tjp) {
-            mergedRel8ns.branch_tjp = mergeBranchAddrs(
-                indexIbGib.rel8ns?.branch_tjp || [],
-                rel8nsToUpdate?.branch_tjp || [],
-            );
-        }
-
-        delete mergedRel8ns.past;
-
-        const res = await Factory_V1.firstGen({
-            parentIbGib: ROOT,
-            ib: indexIbGib.ib,
-            data: mergedData,
-            rel8ns: mergedRel8ns,
-        });
-
-        const newIndexIbGib = res.newIbGib as B2tFSIndexIbGib_V1;
-        await persistTransformResult({ resTransform: res, space });
-        if (metaspace.zeroSpace && metaspace.zeroSpace !== space) {
-            await persistTransformResult({ resTransform: res, space: metaspace.zeroSpace });
-        }
-        await metaspace.registerNewIbGib({ ibGib: newIndexIbGib });
-
-        if (vcsPath) {
-            await writeVcsIndexProjection({ vcsPath, indexIbGib: newIndexIbGib });
-        }
-
-        return newIndexIbGib;
-    } catch (error) {
-        console.error(`${lc} ${extractErrorMsg(error)} (E: 1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f)`);
-        throw error;
-    } finally {
-        if (logalot) {
-            console.log(`${lc} complete. (I: 2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a)`);
-        }
-    }
-}
-
-/**
- * Writes read-only JSON projection cache of repository index.
- */
-export async function writeVcsIndexProjection({
-    vcsPath,
-    indexIbGib,
-}: {
-    vcsPath: string;
-    indexIbGib: B2tFSIndexIbGib_V1;
-}): Promise<void> {
-    const lc = `${lcFile}[${writeVcsIndexProjection.name}]`;
-    try {
-        if (logalot) {
-            console.log(`${lc} starting... (I: 3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b)`);
-        }
-
-        await fs.mkdir(vcsPath, { recursive: true });
-
-        const indexAddr = getIbGibAddr({ ibGib: indexIbGib });
-        const projectionObj = {
-            _isReadOnlyProjection: true,
-            _comment: 'STRICTLY READ-ONLY PROJECTION GENERATED FROM B2TFSINDEXIBGIB_V1 IN LOCALSPACE',
-            indexAddr,
-            spaceId: indexIbGib.data?.mySpaceId,
-            activeBranch: indexIbGib.data?.activeBranch || 'main',
-            stagedCount: (indexIbGib.data?.staged_item || []).length,
-            stagedPaths: indexIbGib.data?.stagedPaths || {},
-            updatedAt: new Date().toISOString(),
-        };
-
-        const projFile = path.join(vcsPath, 'vcs_index_projection.json');
-        await fs.writeFile(projFile, JSON.stringify(projectionObj, null, 2), 'utf8');
-    } catch (error) {
-        console.error(`${lc} ${extractErrorMsg(error)} (E: 4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c)`);
-        throw error;
-    } finally {
-        if (logalot) {
-            console.log(`${lc} complete. (I: 5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d)`);
-        }
-    }
-}
-
-export interface UnstagePathsFromIndexOpts {
-    indexIbGib: B2tFSIndexIbGib_V1;
-    paths?: string[];
-    targetDir?: string;
-    activeWorktreeDir?: string;
-    vcsPath?: string;
-    space: IbGibSpaceAny;
-    metaspace: MetaspaceService;
-    all?: boolean;
-}
-
-export interface UnstagePathsFromIndexResult {
-    updatedIndex: B2tFSIndexIbGib_V1;
-    unstagedPaths: string[];
-}
-
-/**
- * Unstages specified paths (or all paths if `all` or empty `paths`) from `indexIbGib.data.stagedPaths`
- * and `indexIbGib.data.staged_item`.
- */
-export async function unstagePathsFromIndex({
-    indexIbGib,
-    paths = [],
-    targetDir = process.cwd(),
-    activeWorktreeDir,
-    vcsPath,
-    space,
-    metaspace,
-    all = false,
-}: UnstagePathsFromIndexOpts): Promise<UnstagePathsFromIndexResult> {
-    const lc = `${lcFile}[${unstagePathsFromIndex.name}]`;
-    try {
-        if (logalot) {
-            console.log(`${lc} starting... (I: 6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d)`);
-        }
-
-        const currentStagedPaths = { ...(indexIbGib.data?.stagedPaths || {}) };
-        let currentStagedItems = [...(indexIbGib.data?.staged_item || [])];
-        const unstagedPaths: string[] = [];
-
-        const worktreeDir = activeWorktreeDir || targetDir;
-
-        if (all || paths.length === 0 || (paths.length === 1 && (paths[0] === '.' || paths[0] === ''))) {
-            for (const relPath of Object.keys(currentStagedPaths)) {
-                unstagedPaths.push(relPath);
-            }
-            const updatedIndex = await updateB2tFSIndexIbGib({
-                space,
-                metaspace,
-                indexIbGib,
-                dataToUpdate: {
-                    stagedPaths: {},
-                    staged_item: [],
-                },
-                vcsPath,
-            });
-            return { updatedIndex, unstagedPaths };
-        }
-
-        for (const p of paths) {
-            let relPath = p.replace(/\\/g, '/');
-            if (path.isAbsolute(p)) {
-                relPath = path.relative(worktreeDir, p).replace(/\\/g, '/');
-            } else if (targetDir !== worktreeDir) {
-                const absP = path.resolve(targetDir, p);
-                relPath = path.relative(worktreeDir, absP).replace(/\\/g, '/');
-            }
-
-            const targetKeys = Object.keys(currentStagedPaths).filter((k) => {
-                return k === relPath || k.startsWith(relPath + '/');
-            });
-
-            for (const key of targetKeys) {
-                const record = currentStagedPaths[key];
-                if (record && record.itemAddr) {
-                    currentStagedItems = currentStagedItems.filter((addr) => addr !== record.itemAddr);
-                }
-                delete currentStagedPaths[key];
-                if (!unstagedPaths.includes(key)) {
-                    unstagedPaths.push(key);
-                }
-            }
-        }
-
-        const updatedIndex = await updateB2tFSIndexIbGib({
-            space,
-            metaspace,
-            indexIbGib,
-            dataToUpdate: {
-                stagedPaths: currentStagedPaths,
-                staged_item: currentStagedItems,
-            },
-            vcsPath,
-        });
-
-        return { updatedIndex, unstagedPaths };
-    } catch (error) {
-        console.error(`${lc} ${extractErrorMsg(error)} (E: 7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e)`);
-        throw error;
-    } finally {
-        if (logalot) {
-            console.log(`${lc} complete. (I: 8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f)`);
-        }
-    }
-}
-
-export interface RestoreWorktreePathsOpts {
-    paths?: string[];
-    targetDir?: string;
-    activeWorktreeDir: string;
-    activeBranchSpace: IbGibSpaceAny;
-    metaspace: MetaspaceService;
-    indexIbGib?: B2tFSIndexIbGib_V1;
-    vcsPath?: string;
-}
-
-export interface RestoreWorktreePathsResult {
-    restoredPaths: string[];
-}
-
-/**
- * Restores working tree physical files from committed branch item snapshot.
- */
-export async function restoreWorktreePathsFromSnapshot({
-    paths = [],
-    targetDir = process.cwd(),
-    activeWorktreeDir,
-    activeBranchSpace,
-    metaspace,
-    indexIbGib,
-    vcsPath,
-}: RestoreWorktreePathsOpts): Promise<RestoreWorktreePathsResult> {
-    const lc = `${lcFile}[${restoreWorktreePathsFromSnapshot.name}]`;
-    try {
-        if (logalot) {
-            console.log(`${lc} starting... (I: 9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a)`);
-        }
-
-        let currIndex = indexIbGib;
-        if (!currIndex) {
-            currIndex = await getB2tFSIndexIbGib({ space: activeBranchSpace, vcsPath });
-        }
-        if (!currIndex) {
-            throw new Error(`Repository index B2tFSIndexIbGib_V1 not found (E: 0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b)`);
-        }
-
-        const activeBranch = currIndex.data?.activeBranch || 'main';
-        const branchAddrs = [
-            ...(currIndex.rel8ns?.branch || []),
-            ...(currIndex.rel8ns?.branch_tjp || []),
-        ];
-
-        let branchIbGibs: B2tFSBranchIbGib_V1[] = [];
-        if (branchAddrs.length > 0) {
-            for (const bAddr of branchAddrs) {
-                const bIbGib = await getIbGibWithMetaspaceFallback({
-                    addr: bAddr,
-                    space: activeBranchSpace,
-                    metaspace,
-                });
-                if (bIbGib) {
-                    branchIbGibs.push(bIbGib as B2tFSBranchIbGib_V1);
-                }
-            }
-        }
-
-        const activeBranchIbGib = branchIbGibs.find(
-            (b) => b?.data?.name === activeBranch,
-        ) || (branchIbGibs.at(0) as B2tFSBranchIbGib_V1);
-
-        if (!activeBranchIbGib) {
-            throw new Error(`Branch '${activeBranch}' not found (E: 1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c)`);
-        }
-
-        const rootItemAddr = activeBranchIbGib.rel8ns?.b2tfs_item?.at(0);
-        if (!rootItemAddr) {
-            throw new Error(`Branch '${activeBranch}' has no root item (E: 2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d)`);
-        }
-
-        const rootItem = await getIbGibWithMetaspaceFallback({
-            addr: rootItemAddr,
-            space: activeBranchSpace,
-            metaspace,
-        }) as B2tFSItemIbGib_V1;
-
-        if (!rootItem) {
-            throw new Error(`Root item node '${rootItemAddr}' could not be fetched (E: 3f7e6d5c4b3a2f1e0d9c8b7a6f5e4d3c)`);
-        }
-
-        const committedItemMap = new Map<string, { relPath: string; parentRelPath: string; item: B2tFSItemIbGib_V1 }>();
-
-        await restoreCmd_collectCommittedItems({
-            item: rootItem,
-            parentRelPath: '',
-            space: activeBranchSpace,
-            metaspace,
-            outMap: committedItemMap,
-        });
-
-        const restoredPaths: string[] = [];
-
-        if (paths.length === 0 || (paths.length === 1 && (paths[0] === '.' || paths[0] === ''))) {
-            for (const entry of committedItemMap.values()) {
-                const destPath = path.join(activeWorktreeDir, entry.parentRelPath);
-                await writeB2tFSItemToFS({
-                    item: entry.item,
-                    destPath,
-                    space: activeBranchSpace,
-                    metaspace,
-                });
-                restoredPaths.push(entry.relPath);
-            }
-        } else {
-            for (const p of paths) {
-                let relPath = p.replace(/\\/g, '/');
-                if (path.isAbsolute(p)) {
-                    relPath = path.relative(activeWorktreeDir, p).replace(/\\/g, '/');
-                } else if (targetDir !== activeWorktreeDir) {
-                    const absP = path.resolve(targetDir, p);
-                    relPath = path.relative(activeWorktreeDir, absP).replace(/\\/g, '/');
-                }
-
-                let matchedCount = 0;
-                for (const entry of committedItemMap.values()) {
-                    if (entry.relPath === relPath || entry.relPath.startsWith(relPath + '/')) {
-                        const destPath = path.join(activeWorktreeDir, entry.parentRelPath);
-                        await writeB2tFSItemToFS({
-                            item: entry.item,
-                            destPath,
-                            space: activeBranchSpace,
-                            metaspace,
-                        });
-                        if (!restoredPaths.includes(entry.relPath)) {
-                            restoredPaths.push(entry.relPath);
-                        }
-                        matchedCount++;
-                    }
-                }
-
-                if (matchedCount === 0) {
-                    throw new Error(`pathspec '${p}' did not match any committed file(s) in snapshot (E: 4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c)`);
-                }
-            }
-        }
-
-        return { restoredPaths };
-    } catch (error) {
-        console.error(`${lc} ${extractErrorMsg(error)} (E: 5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b)`);
-        throw error;
-    } finally {
-        if (logalot) {
-            console.log(`${lc} complete. (I: 6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b)`);
-        }
-    }
-}
-
-// #region restoreCmd_collectCommittedItems
-async function restoreCmd_collectCommittedItems({
-    item,
-    parentRelPath,
-    space,
-    metaspace,
-    outMap,
-}: {
-    item: B2tFSItemIbGib_V1;
-    parentRelPath: string;
-    space: IbGibSpaceAny;
-    metaspace: MetaspaceService;
-    outMap: Map<string, { relPath: string; parentRelPath: string; item: B2tFSItemIbGib_V1 }>;
-}): Promise<void> {
-    if (!item || !item.data) { return; }
-
-    const { fsType, name } = item.data;
-
-    if (fsType === 'folder' && !parentRelPath) {
-        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) {
-                await restoreCmd_collectCommittedItems({
-                    item: childItem,
-                    parentRelPath: '',
-                    space,
-                    metaspace,
-                    outMap,
-                });
-            }
-        }
-    } else {
-        const relPath = parentRelPath ? `${parentRelPath}/${name}` : name;
-        outMap.set(relPath, { relPath, parentRelPath, 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) {
-                    await restoreCmd_collectCommittedItems({
-                        item: childItem,
-                        parentRelPath: relPath,
-                        space,
-                        metaspace,
-                        outMap,
-                    });
-                }
-            }
-        }
-    }
-}
-// #endregion restoreCmd_collectCommittedItems