@ibgib/vcs-gib 0.0.6

package/src/cli/commands/branch-checkout-cmd.respec.node.mts

@@ -0,0 +1,322 @@
+/**
+ * @module branch-checkout-cmd.respec
+ * 
+ * Unit tests for `vcs branch` and `vcs checkout` command handlers & worktree projections.
+ */
+
+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 { executeInitCmd } from './init-cmd.mjs';
+import { executeAddCmd } from './add-cmd.mjs';
+import { executeCommitCmd } from './commit-cmd.mjs';
+import { executeBranchCmd } from './branch-cmd.mjs';
+import { executeCheckoutCmd } from './checkout-cmd.mjs';
+import { executeStatusCmd } from './status-cmd.mjs';
+
+const lc = `[apps/vcs-gib/src/cli/commands/branch-checkout-cmd.respec.node.mts]`;
+
+await respecfully(lc, `vcs branch and vcs checkout Command Handlers`, async () => {
+
+    await ifWe(lc, `lists default branch main for new repository`, async () => {
+        const testDir = path.join(process.cwd(), '.test_branch_checkout_1');
+        const vcsFolderName = '.vcsgib_test_bc_1';
+        try {
+            await executeInitCmd({
+                targetDir: testDir,
+                vcsFolderName,
+                quiet: true,
+            });
+
+            const branchRes = await executeBranchCmd({
+                targetDir: testDir,
+                vcsFolderName,
+                quiet: true,
+            });
+
+            iReckon(lc, branchRes.branches.length).willEqual(1);
+            iReckon(lc, branchRes.branches[0].name).willEqual('main');
+            iReckon(lc, branchRes.branches[0].isActive).isGonnaBeTrue();
+        } finally {
+            await fs.rm(testDir, { recursive: true, force: true });
+        }
+    });
+
+    await ifWe(lc, `creates new branch from active branch root item and rejects duplicates`, async () => {
+        const testDir = path.join(process.cwd(), '.test_branch_checkout_2');
+        const vcsFolderName = '.vcsgib_test_bc_2';
+        try {
+            await executeInitCmd({
+                targetDir: testDir,
+                vcsFolderName,
+                quiet: true,
+            });
+
+            // Create feature branch
+            const createRes = await executeBranchCmd({
+                branchName: 'feature-auth',
+                targetDir: testDir,
+                vcsFolderName,
+                quiet: true,
+            });
+
+            iReckon(lc, createRes.createdBranchName).willEqual('feature-auth');
+            iReckon(lc, Boolean(createRes.createdBranchAddr)).isGonnaBeTrue();
+
+            // List branches
+            const listRes = await executeBranchCmd({
+                targetDir: testDir,
+                vcsFolderName,
+                quiet: true,
+            });
+
+            iReckon(lc, listRes.branches.length).willEqual(2);
+            const featureBranch = listRes.branches.find(b => b.name === 'feature-auth');
+            iReckon(lc, Boolean(featureBranch)).isGonnaBeTrue();
+            iReckon(lc, featureBranch?.isActive).isGonnaBeFalse();
+
+            // Verify dedicated branch space subfolders exist in .vcsgib
+            const mainSpaceDir = path.join(testDir, vcsFolderName, 'ibgib', 'b2s_main');
+            const featureSpaceDir = path.join(testDir, vcsFolderName, 'ibgib', 'b2s_feature-auth');
+            const mainSpaceExists = await fs.stat(mainSpaceDir).then(s => s.isDirectory()).catch(() =>
+                fs.stat(path.join(testDir, vcsFolderName, 'b2s_main')).then(s => s.isDirectory()).catch(() => false)
+            );
+            const featureSpaceExists = await fs.stat(featureSpaceDir).then(s => s.isDirectory()).catch(() =>
+                fs.stat(path.join(testDir, vcsFolderName, 'b2s_feature-auth')).then(s => s.isDirectory()).catch(() => false)
+            );
+            iReckon(lc, mainSpaceExists).isGonnaBeTrue();
+            iReckon(lc, featureSpaceExists).isGonnaBeTrue();
+
+            // Duplicate branch attempt
+            let errorThrown = false;
+            try {
+                await executeBranchCmd({
+                    branchName: 'feature-auth',
+                    targetDir: testDir,
+                    vcsFolderName,
+                    quiet: true,
+                });
+            } catch (err: any) {
+                errorThrown = true;
+                iReckon(lc, err.message).includes("already exists");
+            }
+            iReckon(lc, errorThrown).isGonnaBeTrue();
+        } finally {
+            await fs.rm(testDir, { recursive: true, force: true });
+        }
+    });
+
+    await ifWe(lc, `switches active branch with checkout and projects branch snapshot onto worktree subfolder`, async () => {
+        const testDir = path.join(process.cwd(), '.test_branch_checkout_3');
+        const vcsFolderName = '.vcsgib_test_bc_3';
+        try {
+            await executeInitCmd({
+                targetDir: testDir,
+                vcsFolderName,
+                quiet: true,
+            });
+
+            // Commit a file on main
+            await fs.writeFile(path.join(testDir, 'app.ts'), 'console.log("Main");', 'utf8');
+            await executeAddCmd({
+                paths: ['app.ts'],
+                targetDir: testDir,
+                vcsFolderName,
+                quiet: true,
+            });
+            await executeCommitCmd({
+                message: 'Add app.ts on main',
+                targetDir: testDir,
+                vcsFolderName,
+                quiet: true,
+            });
+
+            // Create branch feature-ui
+            await executeBranchCmd({
+                branchName: 'feature-ui',
+                targetDir: testDir,
+                vcsFolderName,
+                quiet: true,
+            });
+
+            // Checkout feature-ui
+            const checkoutRes = await executeCheckoutCmd({
+                branchName: 'feature-ui',
+                targetDir: testDir,
+                vcsFolderName,
+                quiet: true,
+            });
+
+            iReckon(lc, checkoutRes.previousBranch).willEqual('main');
+            iReckon(lc, checkoutRes.currentBranch).willEqual('feature-ui');
+
+            const expectedWorktree = path.join(testDir, 'b', 'feature-ui');
+            iReckon(lc, checkoutRes.worktreePath).willEqual(expectedWorktree);
+
+            // Verify project file exists in worktree path
+            const projectedFile = path.join(expectedWorktree, 'app.ts');
+            const fileContent = await fs.readFile(projectedFile, 'utf8');
+            iReckon(lc, fileContent).willEqual('console.log("Main");');
+
+            // Verify active branch in status
+            const statusRes = await executeStatusCmd({
+                targetDir: testDir,
+                vcsFolderName,
+                quiet: true,
+            });
+            iReckon(lc, statusRes.branchName).willEqual('feature-ui');
+
+            // Verify branch list displays ALL branches while on feature-ui
+            const branchListOnFeature = await executeBranchCmd({
+                targetDir: testDir,
+                vcsFolderName,
+                quiet: true,
+            });
+            iReckon(lc, branchListOnFeature.branches.length).willEqual(2);
+            iReckon(lc, branchListOnFeature.branches.map(b => b.name)).includes('main');
+            iReckon(lc, branchListOnFeature.branches.map(b => b.name)).includes('feature-ui');
+
+            // Make a commit on feature-ui branch
+            await fs.writeFile(path.join(expectedWorktree, 'ui.ts'), 'export const ui = 1;', 'utf8');
+            await executeAddCmd({
+                paths: ['ui.ts'],
+                targetDir: expectedWorktree,
+                vcsFolderName,
+                quiet: true,
+            });
+            await executeCommitCmd({
+                message: 'Add ui.ts on feature-ui',
+                targetDir: expectedWorktree,
+                vcsFolderName,
+                quiet: true,
+            });
+
+            // Verify branch list after commit on feature-ui still displays ALL branches
+            const branchListAfterCommit = await executeBranchCmd({
+                targetDir: expectedWorktree,
+                vcsFolderName,
+                quiet: true,
+            });
+            iReckon(lc, branchListAfterCommit.branches.length).willEqual(2);
+
+            // Switch back to main
+            const switchBackRes = await executeCheckoutCmd({
+                branchName: 'main',
+                targetDir: expectedWorktree,
+                vcsFolderName,
+                quiet: true,
+            });
+            iReckon(lc, switchBackRes.currentBranch).willEqual('main');
+            iReckon(lc, switchBackRes.worktreePath).willEqual(testDir);
+
+            // Verify branch list displays ALL branches while on main after feature-ui commit
+            const branchListOnMain = await executeBranchCmd({
+                targetDir: testDir,
+                vcsFolderName,
+                quiet: true,
+            });
+            iReckon(lc, branchListOnMain.branches.length).willEqual(2);
+            iReckon(lc, branchListOnMain.branches.map(b => b.name)).includes('main');
+            iReckon(lc, branchListOnMain.branches.map(b => b.name)).includes('feature-ui');
+
+            // Switch back to feature-ui seamlessly
+            const switchAgainRes = await executeCheckoutCmd({
+                branchName: 'feature-ui',
+                targetDir: testDir,
+                vcsFolderName,
+                quiet: true,
+            });
+            iReckon(lc, switchAgainRes.currentBranch).willEqual('feature-ui');
+        } finally {
+            await fs.rm(testDir, { recursive: true, force: true });
+        }
+    });
+
+    await ifWe(lc, `rejects checkout when branch does not exist or branchName missing`, async () => {
+        const testDir = path.join(process.cwd(), '.test_branch_checkout_4');
+        const vcsFolderName = '.vcsgib_test_bc_4';
+        try {
+            await executeInitCmd({
+                targetDir: testDir,
+                vcsFolderName,
+                quiet: true,
+            });
+
+            let err1 = false;
+            try {
+                await executeCheckoutCmd({
+                    branchName: '',
+                    targetDir: testDir,
+                    vcsFolderName,
+                    quiet: true,
+                });
+            } catch (err: any) {
+                err1 = true;
+                iReckon(lc, err.message).includes('Branch name is required');
+            }
+            iReckon(lc, err1).isGonnaBeTrue();
+
+            let err2 = false;
+            try {
+                await executeCheckoutCmd({
+                    branchName: 'non-existent-branch',
+                    targetDir: testDir,
+                    vcsFolderName,
+                    quiet: true,
+                });
+            } catch (err: any) {
+                err2 = true;
+                iReckon(lc, err.message).includes("does not exist");
+            }
+            iReckon(lc, err2).isGonnaBeTrue();
+        } finally {
+            await fs.rm(testDir, { recursive: true, force: true });
+        }
+    });
+
+    await ifWe(lc, `lists branches silently on secondary branch without error noise`, async () => {
+        const testDir = path.join(process.cwd(), '.test_branch_checkout_secondary');
+        const vcsFolderName = '.vcsgib_test_bc_sec';
+        try {
+            await executeInitCmd({
+                targetDir: testDir,
+                vcsFolderName,
+                quiet: true,
+            });
+
+            // Create and checkout secondary branch feature-math
+            await executeBranchCmd({
+                branchName: 'feature-math',
+                targetDir: testDir,
+                vcsFolderName,
+                quiet: true,
+            });
+
+            await executeCheckoutCmd({
+                branchName: 'feature-math',
+                targetDir: testDir,
+                vcsFolderName,
+                quiet: true,
+            });
+
+            // Run branch list while on secondary branch
+            const listRes = await executeBranchCmd({
+                targetDir: testDir,
+                vcsFolderName,
+                quiet: true,
+            });
+
+            iReckon(lc, listRes.branches.length).willEqual(2);
+            const mathBranch = listRes.branches.find(b => b.name === 'feature-math');
+            const mainBranch = listRes.branches.find(b => b.name === 'main');
+            iReckon(lc, mathBranch?.isActive).isGonnaBeTrue();
+            iReckon(lc, mainBranch?.isActive).isGonnaBeFalse();
+        } finally {
+            await fs.rm(testDir, { recursive: true, force: true });
+        }
+    });
+});

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

@@ -0,0 +1,243 @@
+/**
+ * @module branch-cmd
+ * 
+ * Command handler for `vcs branch [branchName]`.
+ * Lists registered branches or creates a new B2tFSBranchIbGib_V1 node registered in B2tFSIndexIbGib_V1.
+ */
+
+import path from 'node:path';
+import fs from 'node:fs/promises';
+
+import { extractErrorMsg, getUUID } 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 { createB2tFSBranchIbGib } from '../../engine/branch/branch-helper.mjs';
+import { getOrCreateBranchSpace } from '../../engine/branch/branch-space-helper.mjs';
+import { populateBranchSpaceFromGraph } from '../../engine/branch/branch-graph-helper.mjs';
+import { B2tFSItemIbGib_V1 } from '../../engine/item/item-types.mjs';
+import { getIbGibWithMetaspaceFallback } from '../../engine/item/item-helper.mjs';
+import { getB2tFSIndexIbGib, updateB2tFSIndexIbGib, getSpaceQualifiedIbGibAddr } from '../../engine/index/index-helper.mjs';
+import { GLOBAL_LOG_A_LOT } from '../../vcs-gib-constants.mjs';
+
+const lcFile = `[branch-cmd]`;
+const logalot = GLOBAL_LOG_A_LOT;
+
+export interface BranchCmdOpts {
+    branchName?: string;
+    targetDir?: string;
+    vcsFolderName?: string;
+    quiet?: boolean;
+}
+
+export interface BranchInfo {
+    name: string;
+    isActive: boolean;
+    addr: string;
+    rootItemAddr?: string;
+}
+
+export interface BranchCmdResult {
+    branches: BranchInfo[];
+    createdBranchName?: string;
+    createdBranchAddr?: string;
+}
+
+export async function executeBranchCmd({
+    branchName,
+    targetDir = process.cwd(),
+    vcsFolderName = '.vcsgib',
+    quiet = false,
+}: BranchCmdOpts = {}): Promise<BranchCmdResult> {
+    const lc = `${lcFile}[${executeBranchCmd.name}]`;
+    try {
+        if (logalot) {
+            console.log(`${lc} starting... (I: 4c3d2e1f0a9b8c7d6e5f4a3b2c1d0e9f)`);
+        }
+
+        const absTargetDir = path.resolve(targetDir);
+
+        const { metaspace, localSpace, 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: 5d4e3f2a1b0c9d8e7f6a5b4c3d2e1f0a)`);
+        }
+
+        // 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: 6e5f4a3b2c1d0e9f8a7b6c5d4e3f2a1b)`);
+        }
+
+        const activeBranchName = indexIbGib.data?.activeBranch || 'main';
+
+        // Resolve active branch space b2s_<activeBranch>
+        const { space: activeBranchSpace } = await getOrCreateBranchSpace({
+            metaspace,
+            vcsPath,
+            branchName: activeBranchName,
+        });
+
+        // 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: activeBranchSpace,
+                    metaspace,
+                });
+                if (bIbGib) {
+                    branchIbGibs.push(bIbGib as B2tFSBranchIbGib_V1);
+                }
+            }
+        }
+
+        // Deduplicate branch nodes by branch name
+        const branchMap = new Map<string, B2tFSBranchIbGib_V1>();
+        for (const b of branchIbGibs) {
+            if (b?.data?.name) {
+                branchMap.set(b.data.name, b);
+            }
+        }
+
+        const trimmedBranchName = branchName?.trim();
+
+        if (!trimmedBranchName) {
+            // LIST BRANCHES
+            const branches: BranchInfo[] = [];
+            for (const [name, bNode] of branchMap.entries()) {
+                const addr = getIbGibAddr({ ibGib: bNode });
+                const rootItemAddr = bNode.rel8ns?.b2tfs_item?.at(0);
+                const isActive = name === activeBranchName;
+                branches.push({
+                    name,
+                    isActive,
+                    addr,
+                    rootItemAddr,
+                });
+            }
+
+            if (!quiet) {
+                for (const b of branches) {
+                    const prefix = b.isActive ? '* ' : '  ';
+                    console.log(`${prefix}${b.name}`);
+                }
+            }
+
+            return { branches };
+        }
+
+        // CREATE BRANCH
+        if (branchMap.has(trimmedBranchName)) {
+            throw new Error(`Branch '${trimmedBranchName}' already exists (E: 7f6a5b4c3d2e1f0a9b8c7d6e5f4a3b2c)`);
+        }
+
+        // Find active branch root item to fork from
+        const activeBranchIbGib = branchMap.get(activeBranchName) || branchIbGibs.at(0);
+        const rootItemAddr = activeBranchIbGib?.rel8ns?.b2tfs_item?.at(0);
+
+        if (!rootItemAddr) {
+            throw new Error(`Cannot find active branch root item to fork branch from (E: 8a7b6c5d4e3f2a1b0c9d8e7f6a5b4c3d)`);
+        }
+
+        const rootItem = await getIbGibWithMetaspaceFallback({
+            addr: rootItemAddr,
+            space: activeBranchSpace,
+            metaspace,
+        }) as B2tFSItemIbGib_V1;
+
+        if (!rootItem) {
+            throw new Error(`Root item node for address '${rootItemAddr}' not found in localSpace (E: 9b8c7d6e5f4a3b2c1d0e9f8a7b6c5d4e)`);
+        }
+
+        // Instantiate new branch space b2s_<newBranch>
+        const { space: newBranchSpace, spaceId: newBranchSpaceId } = await getOrCreateBranchSpace({
+            metaspace,
+            vcsPath,
+            branchName: trimmedBranchName,
+        });
+
+        // Populate new branch space from live dependency graph of rootItem
+        await populateBranchSpaceFromGraph({
+            sourceSpace: activeBranchSpace,
+            targetBranchSpace: newBranchSpace,
+            rootItemIbGib: rootItem,
+            metaspace,
+        });
+
+        // Create new B2tFSBranchIbGib_V1 branch node inside newBranchSpace
+        const newBranchIbGib = await createB2tFSBranchIbGib({
+            branchName: trimmedBranchName,
+            rootItem,
+            space: newBranchSpace,
+            metaspace,
+        });
+
+        // Put in activeBranchSpace so active index can reference it
+        await putInSpace({ space: activeBranchSpace, ibGib: newBranchIbGib });
+
+        const newBranchAddr = getIbGibAddr({ ibGib: newBranchIbGib });
+        const sqNewBranchAddr = getSpaceQualifiedIbGibAddr({
+            spaceId: newBranchSpaceId,
+            ibGibAddr: newBranchAddr,
+        });
+
+        // Register new branch node in B2tFSIndexIbGib_V1 using space-qualified address
+        await updateB2tFSIndexIbGib({
+            space: activeBranchSpace,
+            metaspace,
+            indexIbGib,
+            rel8nsToUpdate: {
+                branch: [sqNewBranchAddr],
+                branch_tjp: [sqNewBranchAddr],
+            },
+            vcsPath,
+        });
+
+        if (!quiet) {
+            console.log(`Created branch '${trimmedBranchName}' (I: 0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f)`);
+        }
+
+        // Return updated branch list
+        branchMap.set(trimmedBranchName, newBranchIbGib);
+        const branches: BranchInfo[] = [];
+        for (const [name, bNode] of branchMap.entries()) {
+            const addr = getIbGibAddr({ ibGib: bNode });
+            const itemAddr = bNode.rel8ns?.b2tfs_item?.at(0);
+            branches.push({
+                name,
+                isActive: name === activeBranchName,
+                addr,
+                rootItemAddr: itemAddr,
+            });
+        }
+
+        return {
+            branches,
+            createdBranchName: trimmedBranchName,
+            createdBranchAddr: newBranchAddr,
+        };
+    } catch (error) {
+        console.error(`${lc} ${extractErrorMsg(error)} (E: 1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a)`);
+        throw error;
+    } finally {
+        if (logalot) {
+            console.log(`${lc} complete. (I: 2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b)`);
+        }
+    }
+}