@ibgib/vcs-gib 0.0.32 → 0.0.34

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

@@ -0,0 +1,113 @@
+/**
+ * @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, WorkspaceProjectionSpaceFactory } 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,
+        });
+
+        const fnGetWorkspaceProjectionSpace: WorkspaceProjectionSpaceFactory = async ({
+            worktreeDir,
+            backingSpace,
+        }) => {
+            const { space } = await getOrCreateWorkspaceProjectionSpace({
+                metaspace,
+                workspaceRoot: worktreeDir,
+                vcsFolderName,
+                backingSpace,
+            });
+            return space;
+        };
+
+        // 5. Construct domain facade
+        const repo = new VcsRepository({
+            metaspace,
+            localSpace,
+            workspaceSpace,
+            fnGetWorkspaceProjectionSpace,
+            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 { bootstrapVcsMetaspace } from '../../bootstrap/node-bootstrap.mjs';
 import { getB2tFSItemIb } from '@ibgib/core-gib/dist/vcs/item/item-atom-helper.mjs';
-import { getOrCreateBranchSpace } from '@ibgib/node-gib/dist/vcs/branch-space-helper.mjs';
 import { populateBranchSpaceFromGraph } from '@ibgib/core-gib/dist/vcs/branch/branch-graph-helper.mjs';
-import { getSpaceQualifiedIbGibAddr, parseSpaceQualifiedIbGibAddr } from '@ibgib/core-gib/dist/vcs/index/index-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';
 
-const lc = `[apps/vcs-gib/src/engine/branch/branch-space.respec.node.mts]`;
+import { bootstrapVcsMetaspace } from '../../bootstrap/node-bootstrap.mjs';
+
+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 { bootstrapVcsMetaspace } from '../../bootstrap/node-bootstrap.mjs';
-import { getOrCreateBranchSpace } from '@ibgib/node-gib/dist/vcs/branch-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';
 
-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

@@ -21,7 +21,8 @@ import { getLatestAddrs } from '@ibgib/core-gib/dist/witness/space/space-helper.
 import { IbGibSpaceAny } from '@ibgib/core-gib/dist/witness/space/space-base-v1.mjs';
 
 import { B2tFSBranchIbGib_V1 } from '@ibgib/core-gib/dist/vcs/branch/branch-types.mjs';
-import { B2tFSItemIbGib_V1 } from '@ibgib/core-gib/dist/vcs/item/item-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

@@ -11,19 +11,17 @@ import fs from 'node:fs/promises';
 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, getSpaceQualifiedIbGibAddr,
-    parseSpaceQualifiedIbGibAddr
-} from '@ibgib/core-gib/dist/vcs/index/index-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';
 
-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 () => {
 
@@ -36,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');
         });
     });
 
@@ -80,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 {