@ibgib/vcs-gib 0.0.30 → 0.0.33

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

@@ -10,17 +10,17 @@ import { extractErrorMsg } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs
 
 import { parseVcsArgs } from './cli-arg-parser.mjs';
 import { VCS_SUBCOMMANDS } from './cli-constants.mjs';
-import { executeInitCmd } from './commands/init-cmd.mjs';
-import { executeStatusCmd } from './commands/status-cmd.mjs';
-import { executeAddCmd } from './commands/add-cmd.mjs';
-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 { executeGenerateCommentCmd } from './commands/generate-comment-cmd.mjs';
+import { executeInitCmd } from './commands/cli-init-cmd.mjs';
+import { executeStatusCmd } from './commands/cli-status-cmd.mjs';
+import { executeAddCmd } from './commands/cli-add-cmd.mjs';
+import { executeCommitCmd } from './commands/cli-commit-cmd.mjs';
+import { executeLogCmd } from './commands/cli-log-cmd.mjs';
+import { executeBranchCmd } from './commands/cli-branch-cmd.mjs';
+import { executeCheckoutCmd } from './commands/cli-checkout-cmd.mjs';
+import { executeMergeCmd } from './commands/cli-merge-cmd.mjs';
+import { executeResetCmd } from './commands/cli-reset-cmd.mjs';
+import { executeRestoreCmd } from './commands/cli-restore-cmd.mjs';
+import { executeGenerateCommentCmd } from './commands/cli-generate-comment-cmd.mjs';
 import { AUTO_GENERATED_VERSION } from '../AUTO-GENERATED-version.mjs';
 import { GLOBAL_LOG_A_LOT } from '../vcs-gib-constants.mjs';
 
@@ -76,7 +76,7 @@ export async function main({
     const lc = `${lcFile}[${main.name}]`;
     try {
         if (logalot) {
-            console.log(`${lc} starting... (I: 4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e)`);
+            console.log(`${lc} starting... (I: genuuid)`);
         }
 
         const parsed = parseVcsArgs(argv);
@@ -140,7 +140,10 @@ export async function main({
             }
             case VCS_SUBCOMMANDS.CHECKOUT: {
                 const branchName = parsed.positionals[0] || parsed.flags.branchName;
-                await executeCheckoutCmd({ branchName });
+                await executeCheckoutCmd({
+                    branchName,
+                    force: parsed.flags.force,
+                });
                 break;
             }
             case VCS_SUBCOMMANDS.MERGE: {
@@ -180,11 +183,11 @@ export async function main({
 
         return 0;
     } catch (error) {
-        console.error(`Error: ${extractErrorMsg(error)} (E: 8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d)`);
+        console.error(`Error: ${extractErrorMsg(error)} (E: genuuid)`);
         return 1;
     } finally {
         if (logalot) {
-            console.log(`${lc} complete. (I: 9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c)`);
+            console.log(`${lc} complete. (I: genuuid)`);
         }
     }
 }

package/src/cli/vcs-projection-helper.mts

@@ -0,0 +1,112 @@
+/**
+ * @module vcs-projection-helper
+ *
+ * CLI-specific filesystem projection helpers for reading and writing `.vcsgib/vcs_index_projection.json`.
+ * Strictly housed in `apps/vcs-gib` CLI layer to maintain pure isolation from `core-gib`.
+ */
+
+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 { 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 { B2tFSIndexIbGib_V1 } from '@ibgib/core-gib/dist/vcs/index/index-types.mjs';
+import { GLOBAL_LOG_A_LOT } from '../vcs-gib-constants.mjs';
+
+const lcFile = `[vcs-projection-helper]`;
+const logalot = GLOBAL_LOG_A_LOT;
+
+/**
+ * Retrieves authoritative B2tFSIndexIbGib_V1 from space by reading the `.vcsgib/vcs_index_projection.json` pointer on disk.
+ */
+export async function readVcsIndexProjectionFromDisk({
+    vcsPath,
+    space,
+}: {
+    vcsPath: string;
+    space: IbGibSpaceAny;
+}): Promise<B2tFSIndexIbGib_V1 | undefined> {
+    const lc = `${lcFile}[${readVcsIndexProjectionFromDisk.name}]`;
+    try {
+        if (logalot) {
+            console.log(`${lc} starting... (I: genuuid)`);
+        }
+
+        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: genuuid)`);
+        throw error;
+    } finally {
+        if (logalot) {
+            console.log(`${lc} complete. (I: genuuid)`);
+        }
+    }
+}
+
+/**
+ * Writes read-only JSON projection cache of repository index to disk.
+ */
+export async function writeVcsIndexProjectionToDisk({
+    vcsPath,
+    indexIbGib,
+}: {
+    vcsPath: string;
+    indexIbGib: B2tFSIndexIbGib_V1;
+}): Promise<void> {
+    const lc = `${lcFile}[${writeVcsIndexProjectionToDisk.name}]`;
+    try {
+        if (logalot) {
+            console.log(`${lc} starting... (I: 06da189dd09843652865d2c82e415826)`);
+        }
+
+        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,
+            activeBranchName: indexIbGib.data?.activeBranchName || '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: genuuid)`);
+        throw error;
+    } finally {
+        if (logalot) {
+            console.log(`${lc} complete. (I: genuuid)`);
+        }
+    }
+}

package/src/cli/vcs-repo-helper.mts

@@ -0,0 +1,99 @@
+/**
+ * @module vcs-repo-helper
+ *
+ * Helper to bootstrap Node environment and open a VcsRepository session.
+ */
+
+import path from 'node:path';
+import fs from 'node:fs/promises';
+
+import { extractErrorMsg } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
+import { VcsRepository } from '@ibgib/core-gib/dist/vcs/vcs-repository.mjs';
+import { resolveContextualBranchName } from '@ibgib/core-gib/dist/vcs/branch/branch-helper.mjs';
+import { getB2tFSIndexIbGib } from '@ibgib/core-gib/dist/vcs/index/index-helper.mjs';
+import { getOrCreateBranchSpace } from '@ibgib/core-gib/dist/vcs/branch/branch-helper.mjs';
+import { getOrCreateWorkspaceProjectionSpace } from '@ibgib/node-gib/dist/vcs/workspace-space-helper.mjs';
+
+import { GLOBAL_LOG_A_LOT } from '../vcs-gib-constants.mjs';
+import { bootstrapVcsMetaspace } from '../bootstrap/node-bootstrap.mjs';
+import { B2TFS_BRANCH_DEFAULT_NAME } from '@ibgib/core-gib/dist/vcs/branch/branch-constants.mjs';
+
+const logalot = GLOBAL_LOG_A_LOT;
+
+export interface OpenVcsRepositoryOpts {
+    targetDir?: string;
+    vcsFolderName?: string;
+    branchName?: string;
+}
+
+export interface OpenVcsRepositoryResult {
+    repo: VcsRepository;
+    repoRoot: string;
+    vcsPath: string;
+    activeWorktreeDir: string;
+}
+
+export async function openVcsRepository({
+    targetDir = process.cwd(),
+    vcsFolderName = '.vcsgib',
+    branchName,
+}: OpenVcsRepositoryOpts = {}): Promise<OpenVcsRepositoryResult> {
+    const lc = `[${openVcsRepository.name}]`;
+    try {
+        if (logalot) { console.log(`${lc} starting... (I: 4a621eb5576a3064f85177c6de80a826)`); }
+
+        const absTargetDir = path.resolve(targetDir);
+
+        // 1. Locate repository root and bootstrap Node localSpace
+        const { metaspace, localSpace, vcsPath, repoRoot } = await bootstrapVcsMetaspace({
+            repoPath: absTargetDir,
+            vcsFolderName,
+        });
+
+        // 2. Fetch authoritative in-band index from localSpace
+        const indexIbGib = await getB2tFSIndexIbGib({ space: localSpace, metaspace });
+        if (!indexIbGib) {
+            throw new Error(`Not an ibgib repository (index not found in ${vcsPath})`);
+        }
+
+        // 3. Determine active branch and worktree directory
+        const activeBranchName = branchName || resolveContextualBranchName({
+            targetDir: absTargetDir,
+            repoRoot,
+            indexIbGib,
+        });
+
+        const activeWorktreeDir = activeBranchName === B2TFS_BRANCH_DEFAULT_NAME
+            ? repoRoot
+            : path.join(repoRoot, 'b', activeBranchName);
+
+        // 4. Resolve branch space & create Node workspace projection space
+        const { space: activeSpace } = await getOrCreateBranchSpace({
+            metaspace,
+            branchName: activeBranchName,
+        });
+
+        const { space: workspaceSpace } = await getOrCreateWorkspaceProjectionSpace({
+            metaspace,
+            workspaceRoot: activeWorktreeDir,
+            vcsFolderName,
+            backingSpace: activeSpace,
+        });
+
+        // 5. Construct domain facade
+        const repo = new VcsRepository({
+            metaspace,
+            localSpace,
+            workspaceSpace,
+            repoRoot,
+            vcsFolderName,
+        });
+
+        return { repo, repoRoot, activeWorktreeDir, vcsPath };
+    } catch (error) {
+        console.error(`${lc} ${extractErrorMsg(error)}`);
+        throw error;
+    } finally {
+        if (logalot) { console.log(`${lc} complete.`); }
+    }
+}

package/src/engine/branch/branch-space.respec.mts

@@ -1,6 +1,6 @@
 /**
  * @module branch-space.respec.node
- * 
+ *
  * Unit tests for branch space helper, space-qualified address formatting/parsing,
  * and graph population into branch spaces.
  */
@@ -8,44 +8,49 @@
 import path from 'node:path';
 import fs from 'node:fs/promises';
 
-import {
-    respecfully, ifWe, iReckon
-} from '@ibgib/helper-gib/dist/respec-gib/respec-gib.mjs';
+import { respecfully, ifWe, iReckon } from '@ibgib/helper-gib/dist/respec-gib/respec-gib.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 { getFromSpace, persistTransformResult } from '@ibgib/core-gib/dist/witness/space/space-helper.mjs';
+import { getB2tFSItemIb } from '@ibgib/core-gib/dist/vcs/item/item-atom-helper.mjs';
+import { populateBranchSpaceFromGraph } from '@ibgib/core-gib/dist/vcs/branch/branch-graph-helper.mjs';
+import { B2tFSItemIbGib_V1 } from '@ibgib/core-gib/dist/vcs/item/item-types.mjs';
+import { getOrCreateBranchSpace } from '@ibgib/core-gib/dist/vcs/branch/branch-helper.mjs';
+import { getSpaceQualifiedIbGibAddr, parseSpaceQualifiedIbGibAddr, isSpaceQualifiedAddr } from '@ibgib/core-gib/dist/common/other/ibgib-helper.mjs';
 
 import { bootstrapVcsMetaspace } from '../../bootstrap/node-bootstrap.mjs';
-import { getB2tFSItemIb } from '../item/item-atom-helper.mjs';
-import { getOrCreateBranchSpace } from './branch-space-helper.mjs';
-import { populateBranchSpaceFromGraph } from './branch-graph-helper.mjs';
-import { getSpaceQualifiedIbGibAddr, parseSpaceQualifiedIbGibAddr } from '../index/index-helper.mjs';
-import { B2tFSItemIbGib_V1 } from '../item/item-types.mjs';
 
-const lc = `[apps/vcs-gib/src/engine/branch/branch-space.respec.node.mts]`;
+const lc = `[apps/vcs-gib/src/engine/branch/branch-space.respec.mts]`;
 
 await respecfully(lc, `Branch Space & Graph Helper Respecs`, async () => {
 
     await respecfully(lc, `Space-Qualified Address Parsing & Formatting`, async () => {
         await ifWe(lc, `formats space-qualified address using options object`, async () => {
-            const sq = getSpaceQualifiedIbGibAddr({ spaceId: 'sp_alpha', ibGibAddr: 'item_a^gib123' });
-            iReckon(lc, sq).willEqual('v:1^spaceId:sp_alpha^item_a^gib123');
+            const sq = getSpaceQualifiedIbGibAddr({ spaceId: 'sp_alpha', ibGibAddr: 'item_a^gib' });
+            iReckon(lc, sq).willEqual('v:1^spaceId:sp_alpha^item_a^gib');
         });
 
         await ifWe(lc, `parses space-qualified address using options object`, async () => {
-            const parsed = parseSpaceQualifiedIbGibAddr({ spaceQualifiedAddr: 'v:1^spaceId:sp_alpha^item_a^gib123' });
+            const parsed = parseSpaceQualifiedIbGibAddr({ sqAddr: 'v:1^spaceId:sp_alpha^item_a^gib' });
             iReckon(lc, parsed).isGonnaBeTruthy();
             iReckon(lc, parsed!.version).willEqual(1);
             iReckon(lc, parsed!.spaceId).willEqual('sp_alpha');
-            iReckon(lc, parsed!.ibGibAddr).willEqual('item_a^gib123');
+            iReckon(lc, parsed!.ibGibAddr).willEqual('item_a^gib');
             iReckon(lc, parsed!.ib).willEqual('item_a');
-            iReckon(lc, parsed!.gib).willEqual('gib123');
+            iReckon(lc, parsed!.gib).willEqual('gib');
         });
 
-        await ifWe(lc, `returns null for invalid space-qualified address string`, async () => {
-            const parsed = parseSpaceQualifiedIbGibAddr({ spaceQualifiedAddr: 'invalid_address_string' });
-            iReckon(lc, parsed).isGonnaBeFalsy();
+        await ifWe(lc, `throws for invalid space-qualified address string`, async () => {
+            let threw = false;
+            try {
+                parseSpaceQualifiedIbGibAddr({ sqAddr: 'invalid_address_string' });
+            } catch {
+                threw = true;
+            }
+            iReckon(lc, threw).isGonnaBeTrue();
+            iReckon(lc, isSpaceQualifiedAddr('invalid_address_string')).isGonnaBeFalse();
         });
     });
 
@@ -62,7 +67,6 @@ await respecfully(lc, `Branch Space & Graph Helper Respecs`, async () => {
                 const branchName = 'feature_alpha';
                 const result1 = await getOrCreateBranchSpace({
                     metaspace,
-                    vcsPath,
                     branchName,
                 });
 
@@ -72,7 +76,6 @@ await respecfully(lc, `Branch Space & Graph Helper Respecs`, async () => {
 
                 const result2 = await getOrCreateBranchSpace({
                     metaspace,
-                    vcsPath,
                     branchName,
                 });
 
@@ -132,7 +135,6 @@ await respecfully(lc, `Branch Space & Graph Helper Respecs`, async () => {
                 // Create target branch space
                 const { space: targetBranchSpace } = await getOrCreateBranchSpace({
                     metaspace,
-                    vcsPath,
                     branchName: 'main',
                 });
 

package/src/engine/merge/b2tfs-sync-comments.respec.mts

@@ -25,14 +25,14 @@ import { createCommentIbGib } from '@ibgib/core-gib/dist/common/comment/comment-
 import { getBinIb } from '@ibgib/core-gib/dist/common/other/ibgib-helper.mjs';
 import { BinIbGib_V1 } from '@ibgib/core-gib/dist/common/bin/bin-types.mjs';
 import { putInSpace, persistTransformResult, registerNewIbGib, getFromSpace, getLatestAddrs } from '@ibgib/core-gib/dist/witness/space/space-helper.mjs';
+import { createB2tFSItemIbGib, evolveB2tFSItemIbGib } from '@ibgib/core-gib/dist/vcs/item/item-helper.mjs';
+import { B2tFSItemIbGib_V1, BINARY_REL8N_NAME } from '@ibgib/core-gib/dist/vcs/item/item-types.mjs';
+import { B2tFS3WayGraftStrategy } from '@ibgib/core-gib/dist/vcs/merge/b2tfs-3way-graft-strategy.mjs';
+import { getOrCreateBranchSpace } from '@ibgib/core-gib/dist/vcs/branch/branch-helper.mjs';
 
 import { bootstrapVcsMetaspace } from '../../bootstrap/node-bootstrap.mjs';
-import { getOrCreateBranchSpace } from '../branch/branch-space-helper.mjs';
-import { createB2tFSItemIbGib, evolveB2tFSItemIbGib } from '../item/item-helper.mjs';
-import { B2tFSItemIbGib_V1, BINARY_REL8N_NAME } from '../item/item-types.mjs';
-import { B2tFS3WayGraftStrategy } from './b2tfs-3way-graft-strategy.mjs';
 
-const lc = `[apps/vcs-gib/src/engine/merge/b2tfs-sync-comments.respec.node.mts]`;
+const lc = `[apps/vcs-gib/src/engine/merge/b2tfs-sync-comments.respec.mts]`;
 const graftStrategySvc = GraftStrategyService.instance;
 
 async function createFileWithBinAndComment({
@@ -149,8 +149,8 @@ await respecfully(lc, `B2tFS Item & Comment Sync Graph Integrity`, async () => {
                 repoPath: testDir,
                 vcsFolderName,
             });
-            const { space: spaceA } = await getOrCreateBranchSpace({ metaspace, vcsPath, branchName: 'branch_a' });
-            const { space: spaceB } = await getOrCreateBranchSpace({ metaspace, vcsPath, branchName: 'branch_b' });
+            const { space: spaceA } = await getOrCreateBranchSpace({ metaspace, branchName: 'branch_a' });
+            const { space: spaceB } = await getOrCreateBranchSpace({ metaspace, branchName: 'branch_b' });
 
             // 1. Create file item with comment in Space A
             const { fileItem } = await createFileWithBinAndComment({
@@ -208,8 +208,8 @@ await respecfully(lc, `B2tFS Item & Comment Sync Graph Integrity`, async () => {
                 repoPath: testDir,
                 vcsFolderName,
             });
-            const { space: spaceA } = await getOrCreateBranchSpace({ metaspace, vcsPath, branchName: 'branch_a' });
-            const { space: spaceB } = await getOrCreateBranchSpace({ metaspace, vcsPath, branchName: 'branch_b' });
+            const { space: spaceA } = await getOrCreateBranchSpace({ metaspace, branchName: 'branch_a' });
+            const { space: spaceB } = await getOrCreateBranchSpace({ metaspace, branchName: 'branch_b' });
 
             // 1. Create file with comment 1 in Space A
             const { fileItem: fileItemA1 } = await createFileWithBinAndComment({
@@ -299,8 +299,8 @@ await respecfully(lc, `B2tFS Item & Comment Sync Graph Integrity`, async () => {
                 repoPath: testDir,
                 vcsFolderName,
             });
-            const { space: spaceA } = await getOrCreateBranchSpace({ metaspace, vcsPath, branchName: 'branch_a' });
-            const { space: spaceB } = await getOrCreateBranchSpace({ metaspace, vcsPath, branchName: 'branch_b' });
+            const { space: spaceA } = await getOrCreateBranchSpace({ metaspace, branchName: 'branch_a' });
+            const { space: spaceB } = await getOrCreateBranchSpace({ metaspace, branchName: 'branch_b' });
 
             // 1. Initial base file in Space A
             const { fileItem: lcaFile } = await createFileWithBinAndComment({

package/src/test/test-helpers.mts

@@ -20,8 +20,9 @@ import { IbGibAddr } from '@ibgib/ts-gib/dist/types.mjs';
 import { getLatestAddrs } from '@ibgib/core-gib/dist/witness/space/space-helper.mjs';
 import { IbGibSpaceAny } from '@ibgib/core-gib/dist/witness/space/space-base-v1.mjs';
 
-import { B2tFSBranchIbGib_V1 } from '../engine/branch/branch-types.mjs';
-import { B2tFSItemIbGib_V1 } from '../engine/item/item-types.mjs';
+import { B2tFSBranchIbGib_V1 } from '@ibgib/core-gib/dist/vcs/branch/branch-types.mjs';
+import { B2tFSItemIbGib_V1, B2TFS_CHILD_ITEM_REL8N_NAME } from '@ibgib/core-gib/dist/vcs/item/item-types.mjs';
+import { getIbGibFromSpace } from '@ibgib/core-gib/dist/common/other/ibgib-helper.mjs';
 
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -166,3 +167,50 @@ export function logAddr(label: string, addr: IbGibAddr | undefined): void {
 export function logAddrs(label: string, addrs: IbGibAddr[] | undefined): void {
     console.log(`[ADDRS][${label}]: ${shortAddrs(addrs)}`);
 }
+
+/**
+ * Recursively logs the b2tfs item hierarchy from a rootItemAddr within a space.
+ */
+export async function logTreeHierarchy({
+    label,
+    rootItemAddr,
+    space,
+    metaspace,
+}: {
+    label: string;
+    rootItemAddr?: string;
+    space: any;
+    metaspace?: any;
+}): Promise<void> {
+    const lc = `[TRACE_B2TFS][${label}]`;
+    const spaceName = space?.data?.name || space?.data?.spaceSubPath || space?.ib || 'unknown';
+    console.log(`${lc} === Hierarchy for root: ${shortAddr(rootItemAddr)} in space: ${spaceName} ===`);
+    if (!rootItemAddr) {
+        console.log(`${lc} rootItemAddr is falsy`);
+        return;
+    }
+
+    async function walk(addr: string, depth: number, currentPath: string): Promise<void> {
+        const indent = '  '.repeat(depth);
+        const item = await getIbGibFromSpace({ addr, space, metaspace }) as B2tFSItemIbGib_V1;
+        if (!item) {
+            console.log(`${lc}${indent} ❌ MISSING item at ${shortAddr(addr)} (path: ${currentPath})`);
+            return;
+        }
+        const name = item.data?.name || '(root)';
+        const fsType = item.data?.fsType || 'unknown';
+        const comments = item.rel8ns?.comment || [];
+        const children = item.rel8ns?.[B2TFS_CHILD_ITEM_REL8N_NAME] || [];
+        console.log(`${lc}${indent} 📁 ${name} (${fsType}) addr: ${shortAddr(addr)} comments: ${comments.length} children: ${children.length}`);
+        for (const cAddr of comments) {
+            const comment = await getIbGibFromSpace({ addr: cAddr, space, metaspace });
+            console.log(`${lc}${indent}   💬 comment: "${(comment?.data as any)?.text?.slice(0, 50)}"`);
+        }
+        for (const childAddr of children) {
+            await walk(childAddr, depth + 1, currentPath ? `${currentPath}/${name}` : name);
+        }
+    }
+
+    await walk(rootItemAddr, 1, '');
+}
+

package/src/vcs-gib.respec.mts

@@ -1,6 +1,6 @@
 /**
  * @module vcs-gib.respec.node
- * 
+ *
  * Full Engine Cycle Integration Tests for @ibgib/vcs-gib.
  * Tests Metaspace bootstrap, canonical ib atoms, item creation, branch spaces, and index tracking.
  */
@@ -8,19 +8,20 @@
 import path from 'node:path';
 import fs from 'node:fs/promises';
 
-import {
-    respecfully, ifWe, iReckon
-} from '@ibgib/helper-gib/dist/respec-gib/respec-gib.mjs';
+import { respecfully, ifWe, iReckon } from '@ibgib/helper-gib/dist/respec-gib/respec-gib.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 { getB2tFSItemIb } from '@ibgib/core-gib/dist/vcs/item/item-atom-helper.mjs';
+import { createB2tFSBranchIbGib, getB2tFSBranchSpaceName } from '@ibgib/core-gib/dist/vcs/branch/branch-helper.mjs';
+import { createB2tFSIndexIbGib, } from '@ibgib/core-gib/dist/vcs/index/index-helper.mjs';
+import { B2tFSItemIbGib_V1 } from '@ibgib/core-gib/dist/vcs/item/item-types.mjs';
+import { getSpaceQualifiedIbGibAddr, parseSpaceQualifiedIbGibAddr } from '@ibgib/core-gib/dist/common/other/ibgib-helper.mjs';
+import { getSpaceIdFromIb } from '@ibgib/core-gib/dist/witness/space/metaspace/metaspace-innerspace/metaspace-innerspace-helper.mjs';
 
 import { bootstrapVcsMetaspace } from './bootstrap/node-bootstrap.mjs';
-import { getB2tFSItemIb } from './engine/item/item-atom-helper.mjs';
-import { createB2tFSBranchIbGib, getB2tFSBranchSpaceName } from './engine/branch/branch-helper.mjs';
-import { createB2tFSIndexIbGib, getSpaceQualifiedIbGibAddr, parseSpaceQualifiedIbGibAddr } from './engine/index/index-helper.mjs';
-import { B2tFSItemIbGib_V1 } from './engine/item/item-types.mjs';
 
-const lc = `[apps/vcs-gib/src/vcs-gib.respec.node.mts]`;
+const lc = `[apps/vcs-gib/src/vcs-gib.respec.mts]`;
 
 await respecfully(lc, `vcs-gib Full Engine Cycle`, async () => {
 
@@ -33,12 +34,12 @@ await respecfully(lc, `vcs-gib Full Engine Cycle`, async () => {
 
     await respecfully(lc, `Space-Qualified Addresses`, async () => {
         await ifWe(lc, `formats and parses space-qualified addresses`, async () => {
-            const sq = getSpaceQualifiedIbGibAddr('space_a', 'item^gib123');
-            iReckon(lc, sq).willEqual('v:1^spaceId:space_a^item^gib123');
+            const sqAddr = getSpaceQualifiedIbGibAddr({ spaceId: 'space_a', ibGibAddr: 'item^gib' });
+            iReckon(lc, sqAddr).willEqual('v:1^spaceId:space_a^item^gib');
 
-            const parsed = parseSpaceQualifiedIbGibAddr(sq);
+            const parsed = parseSpaceQualifiedIbGibAddr({ sqAddr });
             iReckon(lc, parsed?.spaceId).willEqual('space_a');
-            iReckon(lc, parsed?.ibGibAddr).willEqual('item^gib123');
+            iReckon(lc, parsed?.ibGibAddr).willEqual('item^gib');
         });
     });
 
@@ -77,15 +78,23 @@ await respecfully(lc, `vcs-gib Full Engine Cycle`, async () => {
                     metaspace,
                 });
                 iReckon(lc, branchIbGib.data?.name).willEqual('main');
+                const branchAddr = getIbGibAddr({ ibGib: branchIbGib });
+
+                const localSpaceId = getSpaceIdFromIb(localSpace.ib);
+                const sqBranchAddr = getSpaceQualifiedIbGibAddr({
+                    ibGibAddr: branchAddr,
+                    spaceId: localSpaceId,
+                });
 
                 // Create Index IbGib
                 const indexIbGib = await createB2tFSIndexIbGib({
-                    spaceId: 'local_space_uuid',
-                    activeSpaceId: 'local_space_uuid',
+                    activeSpaceId: localSpaceId,
                     space: localSpace,
+                    activeBranchName: branchName,
+                    sqBranchAddr,
                     metaspace,
                 });
-                iReckon(lc, indexIbGib.data?.mySpaceId).willEqual('local_space_uuid');
+                iReckon(lc, indexIbGib.data?.mySpaceId).willEqual(localSpaceId);
                 iReckon(lc, indexIbGib.data?.staged_item).willEqual([]);
                 iReckon(lc, indexIbGib.rel8ns?.staged_item).isGonnaBeFalsy();
             } finally {