@ibgib/vcs-gib 0.0.32 → 0.0.34

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

@@ -0,0 +1,87 @@
+/**
+ * @module restore-cmd
+ *
+ * CLI command handler for `vcs restore [path...]`.
+ * Delegates to executeVcsRestore and formats terminal output.
+ */
+
+import path from 'node:path';
+import fs from 'node:fs/promises';
+
+import { extractErrorMsg } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
+import { openVcsRepository } from '../vcs-repo-helper.mjs';
+import { GLOBAL_LOG_A_LOT } from '../../vcs-gib-constants.mjs';
+
+const lcFile = `[restore-cmd]`;
+const logalot = GLOBAL_LOG_A_LOT;
+
+export interface RestoreCmdOpts {
+    paths?: string[];
+    staged?: boolean;
+    worktree?: boolean;
+    all?: boolean;
+    yes?: boolean;
+    force?: boolean;
+    targetDir?: string;
+    vcsFolderName?: string;
+    quiet?: boolean;
+}
+
+export interface RestoreCmdResult {
+    restoredPaths: string[];
+    unstagedPaths: string[];
+}
+
+export async function executeRestoreCmd({
+    paths = [],
+    staged = false,
+    worktree = false,
+    all = false,
+    yes = false,
+    force = false,
+    targetDir = process.cwd(),
+    vcsFolderName = '.vcsgib',
+    quiet = false,
+}: RestoreCmdOpts = {}): Promise<RestoreCmdResult> {
+    const lc = `${lcFile}[${executeRestoreCmd.name}]`;
+    try {
+        if (logalot) {
+            console.log(`${lc} starting... (I: genuuid)`);
+        }
+
+        const absTargetDir = path.resolve(targetDir);
+        const { repo, activeWorktreeDir } = await openVcsRepository({ targetDir: absTargetDir, vcsFolderName });
+
+        const restoreRes = await repo.restore({
+            paths,
+            staged,
+            all,
+            targetDir: absTargetDir,
+            activeWorktreeDir,
+        });
+
+        if (!quiet) {
+            if (staged) {
+                for (const unstagedPath of restoreRes.unstagedPaths) {
+                    console.log(`unstaged: ${unstagedPath}`);
+                }
+            } else {
+                for (const restoredPath of restoreRes.restoredPaths) {
+                    console.log(`restored: ${restoredPath}`);
+                }
+            }
+        }
+
+        return {
+            restoredPaths: restoreRes.restoredPaths,
+            unstagedPaths: restoreRes.unstagedPaths,
+        };
+    } catch (error) {
+        console.error(`${lc} ${extractErrorMsg(error)} (E: genuuid)`);
+        throw error;
+    } finally {
+        if (logalot) {
+            console.log(`${lc} complete. (I: genuuid)`);
+        }
+    }
+}

package/src/cli/commands/{status-cmd.mts → cli-status-cmd.mts}

@@ -6,17 +6,10 @@
  */
 
 import path from 'node:path';
-import fs from 'node:fs/promises';
 
 import { extractErrorMsg } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
-import { executeVcsStatus } from '@ibgib/core-gib/dist/vcs/commands/status-cmd.mjs';
 import { VcsStatusItem, PendingCommentInfo } from '@ibgib/core-gib/dist/vcs/status/status-helper.mjs';
-import { resolveContextualBranchName } from '@ibgib/core-gib/dist/vcs/branch/branch-helper.mjs';
-
-import { bootstrapVcsMetaspace } from '../../bootstrap/node-bootstrap.mjs';
-import { getOrCreateBranchSpace } from '@ibgib/node-gib/dist/vcs/branch-space-helper.mjs';
-import { getOrCreateWorkspaceProjectionSpace } from '@ibgib/node-gib/dist/vcs/workspace-space-helper.mjs';
-import { readVcsIndexProjectionFromDisk } from '../vcs-projection-helper.mjs';
+import { openVcsRepository } from '../vcs-repo-helper.mjs';
 import { GLOBAL_LOG_A_LOT } from '../../vcs-gib-constants.mjs';
 
 const lcFile = `[status-cmd]`;
@@ -54,45 +47,10 @@ export async function executeStatusCmd({
         }
 
         const absTargetDir = path.resolve(targetDir);
+        const { repo } = await openVcsRepository({ targetDir: absTargetDir, vcsFolderName });
 
-        const { metaspace, localSpace, vcsPath, repoRoot } = await bootstrapVcsMetaspace({
-            repoPath: absTargetDir,
-            vcsFolderName,
-        });
-
-        // Verify repo exists
-        try {
-            await fs.access(vcsPath);
-        } catch {
-            throw new Error(`Not an ibgib repository (directory ${vcsPath} does not exist) (E: 4d5e6f7a8b9c10d11e12f13a14b15c6d)`);
-        }
-
-        const indexIbGib = await readVcsIndexProjectionFromDisk({ vcsPath, space: localSpace });
-        const branchName = resolveContextualBranchName({ targetDir: absTargetDir, repoRoot, indexIbGib });
-        const activeWorktreeDir = branchName === 'main' ? repoRoot : path.join(repoRoot, 'b', branchName);
-
-        const { space: activeBranchSpace } = await getOrCreateBranchSpace({
-            metaspace,
-            vcsPath,
-            branchName,
-        });
-
-        const { space: workspaceSpace } = await getOrCreateWorkspaceProjectionSpace({
-            metaspace,
-            workspaceRoot: activeWorktreeDir,
-            vcsFolderName,
-            backingSpace: activeBranchSpace,
-        });
-
-        const statusRes = await executeVcsStatus({
-            metaspace,
-            localSpace,
-            activeBranchSpace,
-            workspaceSpace,
-            indexIbGib,
-            repoRoot,
+        const statusRes = await repo.status({
             targetDir: absTargetDir,
-            vcsFolderName,
         });
 
         const { staged, modified, deleted, untracked, pendingComments } = statusRes;

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

@@ -11,23 +11,27 @@ import {
     respecfully, ifWe, ifWeMight, iReckon
 } from '@ibgib/helper-gib/dist/respec-gib/respec-gib.mjs';
 
+import { extractErrorMsg, pretty } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
 import { getDependencyGraph } from '@ibgib/core-gib/dist/common/other/graph-helper.mjs';
-import { getFromSpace } from '@ibgib/core-gib/dist/witness/space/space-helper.mjs';
-import { executeInitCmd } from './init-cmd.mjs';
-import { executeAddCmd } from './add-cmd.mjs';
-import { executeStatusCmd } from './status-cmd.mjs';
-import { executeCommitCmd } from './commit-cmd.mjs';
-import { executeLogCmd } from './log-cmd.mjs';
-import { executeBranchCmd } from './branch-cmd.mjs';
-import { executeCheckoutCmd } from './checkout-cmd.mjs';
-import { executeMergeCmd } from './merge-cmd.mjs';
-import { executeGenerateCommentCmd } from './generate-comment-cmd.mjs';
+import { getLatestAddrs } from '@ibgib/core-gib/dist/witness/space/space-helper.mjs';
+import { getB2tFSIndexIbGib, } from '@ibgib/core-gib/dist/vcs/index/index-helper.mjs';
+import { getOrCreateBranchSpace, parseBranchIb } from '@ibgib/core-gib/dist/vcs/branch/branch-helper.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 { getIbGibFromSpace, parseSpaceQualifiedIbGibAddr } from '@ibgib/core-gib/dist/common/other/ibgib-helper.mjs';
+
+import { executeInitCmd } from './cli-init-cmd.mjs';
+import { executeAddCmd } from './cli-add-cmd.mjs';
+import { executeStatusCmd } from './cli-status-cmd.mjs';
+import { executeCommitCmd } from './cli-commit-cmd.mjs';
+import { executeLogCmd } from './cli-log-cmd.mjs';
+import { executeBranchCmd } from './cli-branch-cmd.mjs';
+import { executeCheckoutCmd } from './cli-checkout-cmd.mjs';
+import { executeMergeCmd } from './cli-merge-cmd.mjs';
+import { executeGenerateCommentCmd } from './cli-generate-comment-cmd.mjs';
 import { bootstrapVcsMetaspace } from '../../bootstrap/node-bootstrap.mjs';
-import { readVcsIndexProjectionFromDisk } from '../vcs-projection-helper.mjs';
-import { getOrCreateBranchSpace } from '@ibgib/node-gib/dist/vcs/branch-space-helper.mjs';
-import { getIbGibWithMetaspaceFallback } from '@ibgib/core-gib/dist/vcs/item/item-helper.mjs';
 
-const lc = `[apps/vcs-gib/src/cli/commands/commit-log-cmd.respec.node.mts]`;
+const lc = `[apps/vcs-gib/src/cli/commands/commit-log-cmd.respec.mts]`;
 
 await respecfully(lc, `vcs commit and vcs log Command Handlers`, async () => {
 
@@ -115,11 +119,11 @@ await respecfully(lc, `vcs commit and vcs log Command Handlers`, async () => {
                 quiet: true,
             });
 
-            const { localSpace: spaceAdd, vcsPath: vcsPathAdd } = await bootstrapVcsMetaspace({
+            const { metaspace: metaspaceAdd, localSpace: spaceAdd } = await bootstrapVcsMetaspace({
                 repoPath: testDir,
                 vcsFolderName,
             });
-            const indexAdd = await readVcsIndexProjectionFromDisk({ space: spaceAdd, vcsPath: vcsPathAdd });
+            const indexAdd = await getB2tFSIndexIbGib({ space: spaceAdd, metaspace: metaspaceAdd });
             iReckon(lc, Boolean(indexAdd?.data?.staged_item && indexAdd.data.staged_item.length > 0)).isGonnaBeTrue();
             iReckon(lc, indexAdd?.rel8ns?.staged_item).isGonnaBeFalsy();
 
@@ -130,11 +134,11 @@ await respecfully(lc, `vcs commit and vcs log Command Handlers`, async () => {
                 quiet: true,
             });
 
-            const { localSpace: spaceCommit, vcsPath: vcsPathCommit } = await bootstrapVcsMetaspace({
+            const { metaspace: metaspaceCommit, localSpace: spaceCommit } = await bootstrapVcsMetaspace({
                 repoPath: testDir,
                 vcsFolderName,
             });
-            const indexCommit = await readVcsIndexProjectionFromDisk({ space: spaceCommit, vcsPath: vcsPathCommit });
+            const indexCommit = await getB2tFSIndexIbGib({ space: spaceCommit, metaspace: metaspaceCommit });
             iReckon(lc, indexCommit?.data?.staged_item).willEqual([]);
             iReckon(lc, indexCommit?.rel8ns?.staged_item).isGonnaBeFalsy();
 
@@ -149,9 +153,11 @@ await respecfully(lc, `vcs commit and vcs log Command Handlers`, async () => {
                 quiet: true,
             });
 
+            console.log(`[TEST-LOG] statusRes: staged=${statusRes.staged.length}, modified=${statusRes.modified.length}, untracked=${statusRes.untracked.length}`);
             iReckon(lc, statusRes.staged.length).willEqual(0);
             iReckon(lc, statusRes.modified.length).willEqual(0);
             iReckon(lc, statusRes.untracked.length).willEqual(0);
+            console.log(`[TEST-LOG] statusRes assertions complete.`);
         } finally {
             await fs.rm(testDir, { recursive: true, force: true });
         }
@@ -434,7 +440,9 @@ await respecfully(lc, `vcs commit and vcs log Command Handlers`, async () => {
             await executeCommitCmd({ message: 'Main branch update', targetDir: testDir, vcsFolderName, quiet: true });
 
             // Merge feature-comments into main
-            await executeMergeCmd({ incomingBranchName: 'feature-comments', targetDir: testDir, vcsFolderName, quiet: true });
+            await executeMergeCmd({
+                incomingBranchName: 'feature-comments', targetDir: testDir, vcsFolderName, quiet: true
+            });
 
             // Check file log on main: both comments should be present!
             const mergedFileLog = await executeLogCmd({
@@ -445,33 +453,71 @@ await respecfully(lc, `vcs commit and vcs log Command Handlers`, async () => {
             });
 
             const allMessages = mergedFileLog.commits.map(c => c.message).join(' -- ');
+            console.log(`allMessages: ${pretty(allMessages)}`);
             iReckon(lc, allMessages).includes('updated b to 200');
             iReckon(lc, allMessages).includes('updated a to 100');
 
             // Verify getDependencyGraph works 100% within main branch space alone (no metaspace fallback)
-            const { metaspace, vcsPath } = await bootstrapVcsMetaspace({
+            const { metaspace, localSpace, vcsPath } = await bootstrapVcsMetaspace({
                 repoPath: testDir,
                 vcsFolderName,
             });
             const { space: mainSpace } = await getOrCreateBranchSpace({
                 metaspace,
-                vcsPath,
                 branchName: 'main',
             });
-            const indexIbGib = await readVcsIndexProjectionFromDisk({ space: metaspace.zeroSpace, vcsPath });
-            const branchAddrs = [
-                ...(indexIbGib?.rel8ns?.branch || []),
-                ...(indexIbGib?.rel8ns?.branch_tjp || []),
-            ];
-            const mainBranchAddr = branchAddrs.find(a => a.includes('main')) || branchAddrs.at(-1);
-            const mainBranch = await getIbGibWithMetaspaceFallback({ addr: mainBranchAddr!, space: mainSpace, metaspace });
-            const mainRootAddr = mainBranch?.rel8ns?.b2tfs_item?.at(-1);
-            const mainRoot = await getIbGibWithMetaspaceFallback({ addr: mainRootAddr!, space: mainSpace, metaspace });
+            const indexIbGib = await getB2tFSIndexIbGib({ space: localSpace, metaspace });
+            if (!indexIbGib) { throw new Error(`(UNEXPECTED) indexIbGib falsy? (E: d4ec1b6f86cbf18808fba957b7b83826)`); }
+            const branchAddrs_spacequalified = indexIbGib.data['$@branch'] ?? [];
+            if (branchAddrs_spacequalified.length === 0) {
+                throw new Error(`(UNEXPECTED) indexIbGib doesn't have any branch addrs in data? (E: 7069280124b81c6d1806fc580c704826)`);
+            }
+            const branchAddrs_spacequalified_main = branchAddrs_spacequalified
+                .filter(x => {
+                    const parsedBranchAddrInfo = parseSpaceQualifiedIbGibAddr({ sqAddr: x });
+                    if (!parsedBranchAddrInfo) { throw new Error(`(UNEXPECTED) parsedBranchAddrInfo falsy? space-qualified branch addr couldn't be parsed? (E: 779b886c5a6d64b0ce0e8c185952b526)`); }
+                    const parsedBranchIb = parseBranchIb({ ib: parsedBranchAddrInfo.ib });
+                    return parsedBranchIb.branchName === 'main';
+                });
+
+            if (branchAddrs_spacequalified_main.length !== 1) { throw new Error(`(UNEXPECTED) branchAddrs_spacequalified_main.length !== 1? (E: 3ec21f70cca8b2347de407abc9062826)`); }
+
+            const mainBranchAddr_spaceQualified = branchAddrs_spacequalified_main[0];
+
+            const mainBranchAddrInfo = parseSpaceQualifiedIbGibAddr({
+                sqAddr: mainBranchAddr_spaceQualified
+            });
+            if (!mainBranchAddrInfo) { throw new Error(`(UNEXPECTED) mainBranchAddrInfo falsy? couldn't parse it? (E: ae570ae49e190727fc4464183ab87226)`); }
+
+            const resLatestMainBranchAddrs = await getLatestAddrs({
+                addrs: [mainBranchAddrInfo.ibGibAddr],
+                space: mainSpace,
+            });
+            if (!resLatestMainBranchAddrs) { throw new Error(`resLatestMainBranchAddrs falsy (E: f22b6325ec6804046899e49d8076d826)`); }
+            if (!resLatestMainBranchAddrs.data) { throw new Error(`(UNEXPECTED) resLatestMainBranchAddrs.data falsy? (E: 2709383cb8943aeb0801bf2541f91826)`); }
+            if (!resLatestMainBranchAddrs.data.latestAddrsMap) { throw new Error(`resLatestMainBranchAddrs.data.latestAddrsMap falsy (E: 4b3824e20968409128270faf093a6826)`); }
+            if (Object.keys(resLatestMainBranchAddrs.data.latestAddrsMap).length !== 1) { throw new Error(`(UNEXPECTED) resLatestMainBranchAddrs.data.latestAddrsMap not size 1? (E: bffbbd29f0222027d824e1b810281826)`); }
+
+            let latestMainAddr =
+                Object.values(resLatestMainBranchAddrs.data.latestAddrsMap).at(0) || mainBranchAddrInfo.ibGibAddr;
+            const latestMainBranchIbGib = await getIbGibFromSpace<B2tFSBranchIbGib_V1>({ addr: latestMainAddr, space: mainSpace });
+            if (!latestMainBranchIbGib) { throw new Error(`(UNEXPECTED) latestMainBranchIbGib? (E: 29b2884d60eac1fb98d512f81af8f826)`); }
+
+            if (!latestMainBranchIbGib.rel8ns) { throw new Error(`(UNEXPECTED) latestMainBranchIbGib.rel8ns falsy? (E: 3c70081bde0d9cce68b857b829472726)`); }
+            if (!latestMainBranchIbGib.rel8ns.b2tfs_item) { throw new Error(`latestMainBranchIbGib.rel8ns.b2tfs_item falsy (E: 6ab0d8c90628c10e020b22b862590f26)`); }
+            const mainRootItemAddr = latestMainBranchIbGib.rel8ns.b2tfs_item.at(-1);
+            if (!mainRootItemAddr) { throw new Error(`(UNEXPECTED) mainRootItemAddr falsy? we always should have a root item related to the branch ibgib. (E: 7897abafda988af1333d3048aa7a9826)`); }
+            const mainRootItem = await getIbGibFromSpace<B2tFSItemIbGib_V1>({ addr: mainRootItemAddr, space: mainSpace, });
+            if (!mainRootItem) { throw new Error(`(UNEXPECTED) mainRootItem falsy? (E: 4e5afe38b7fb1f560494b61a82bdd526)`); }
+            if (!mainRootItem.rel8ns) { throw new Error(`(UNEXPECTED) mainRootItem.rel8ns falsy? (E: 0301644482a6431419243c528f121826)`); }
+
             let appItem: any;
-            for (const childAddr of mainRoot?.rel8ns?.b2tfs_child || []) {
-                const child = await getIbGibWithMetaspaceFallback({ addr: childAddr, space: mainSpace, metaspace });
-                if (child?.data?.name === 'app.ts') {
-                    appItem = child;
+            // Bill: is mainRootItem definitely a folder in this test? someone should double-check this.
+            for (const childAddr of mainRootItem?.rel8ns?.b2tfs_child || []) {
+                const childOfMainRootItem = await getIbGibFromSpace<B2tFSItemIbGib_V1>({ addr: childAddr, space: mainSpace, metaspace });
+                if (!childOfMainRootItem) { throw new Error(`(UNEXPECTED) childOfMainRootItem falsy? (E: 216428e870884ba2e8c854c25f914826)`); }
+                if (childOfMainRootItem.data.name === 'app.ts') {
+                    appItem = childOfMainRootItem;
                     break;
                 }
             }
@@ -486,6 +532,10 @@ await respecfully(lc, `vcs commit and vcs log Command Handlers`, async () => {
             const graphValues = Object.values(depGraph);
             const foundCommentB = graphValues.some(x => (x.data as any)?.text === 'feat(feature-comments): updated b to 200');
             iReckon(lc, foundCommentB).isGonnaBeTruthy();
+        } catch (error) {
+            const emsg = extractErrorMsg(error);
+            console.error(emsg);
+            iReckon(lc, true).asTo(emsg).isGonnaBeFalse();
         } finally {
             await fs.rm(testDir, { recursive: true, force: true });
         }

package/src/cli/commands/init-cmd.respec.mts

@@ -1,6 +1,6 @@
 /**
  * @module init-cmd.respec
- * 
+ *
  * Unit tests for `vcs init` command handler.
  */
 
@@ -12,9 +12,9 @@ import {
     respecfully, ifWe, iReckon
 } from '@ibgib/helper-gib/dist/respec-gib/respec-gib.mjs';
 
-import { executeInitCmd } from './init-cmd.mjs';
+import { executeInitCmd } from './cli-init-cmd.mjs';
 
-const lc = `[apps/vcs-gib/src/cli/commands/init-cmd.respec.node.mts]`;
+const lc = `[apps/vcs-gib/src/cli/commands/init-cmd.respec.mts]`;
 
 await respecfully(lc, `vcs init Command Handler`, async () => {
 

package/src/cli/commands/reset-restore-cmd.respec.mts

@@ -1,6 +1,6 @@
 /**
  * @module reset-restore-cmd.respec
- * 
+ *
  * Unit tests for `vcs reset` and `vcs restore` command handlers.
  */
 
@@ -8,17 +8,17 @@ import path from 'node:path';
 import fs from 'node:fs/promises';
 
 import {
-    respecfully, ifWe, iReckon
+    respecfully, ifWe, iReckon, ifWeMight, // don't remove unused ifWe or ifWeMight
 } 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 { executeStatusCmd } from './status-cmd.mjs';
-import { executeResetCmd } from './reset-cmd.mjs';
-import { executeRestoreCmd } from './restore-cmd.mjs';
+import { executeInitCmd } from './cli-init-cmd.mjs';
+import { executeAddCmd } from './cli-add-cmd.mjs';
+import { executeCommitCmd } from './cli-commit-cmd.mjs';
+import { executeStatusCmd } from './cli-status-cmd.mjs';
+import { executeResetCmd } from './cli-reset-cmd.mjs';
+import { executeRestoreCmd } from './cli-restore-cmd.mjs';
 
-const lc = `[apps/vcs-gib/src/cli/commands/reset-restore-cmd.respec.node.mts]`;
+const lc = `[apps/vcs-gib/src/cli/commands/reset-restore-cmd.respec.mts]`;
 
 await respecfully(lc, `vcs reset and vcs restore Command Handlers`, async () => {
 

package/src/cli/commands/status-add-cmd.respec.mts

@@ -1,6 +1,6 @@
 /**
  * @module status-add-cmd.respec
- * 
+ *
  * Unit tests for `vcs status` and `vcs add` command handlers.
  */
 
@@ -11,14 +11,16 @@ import {
     respecfully, ifWe, ifWeMight, iReckon
 } from '@ibgib/helper-gib/dist/respec-gib/respec-gib.mjs';
 
-import { executeInitCmd } from './init-cmd.mjs';
-import { executeStatusCmd } from './status-cmd.mjs';
-import { executeAddCmd } from './add-cmd.mjs';
-import { executeCommitCmd } from './commit-cmd.mjs';
+import { extractErrorMsg } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
+import { getB2tFSIndexIbGib } from '@ibgib/core-gib/dist/vcs/index/index-helper.mjs';
+
+import { executeInitCmd } from './cli-init-cmd.mjs';
+import { executeStatusCmd } from './cli-status-cmd.mjs';
+import { executeAddCmd } from './cli-add-cmd.mjs';
+import { executeCommitCmd } from './cli-commit-cmd.mjs';
 import { bootstrapVcsMetaspace } from '../../bootstrap/node-bootstrap.mjs';
-import { readVcsIndexProjectionFromDisk } from '../vcs-projection-helper.mjs';
 
-const lc = `[apps/vcs-gib/src/cli/commands/status-add-cmd.respec.node.mts]`;
+const lc = `[apps/vcs-gib/src/cli/commands/status-add-cmd.respec.mts]`;
 
 await respecfully(lc, `vcs status and vcs add Command Handlers`, async () => {
 
@@ -138,11 +140,11 @@ await respecfully(lc, `vcs status and vcs add Command Handlers`, async () => {
 
             iReckon(lc, addRes.stagedPaths).includes('file1.txt');
 
-            const { localSpace, vcsPath } = await bootstrapVcsMetaspace({
+            const { metaspace, localSpace } = await bootstrapVcsMetaspace({
                 repoPath: testDir,
                 vcsFolderName,
             });
-            const indexIbGib = await readVcsIndexProjectionFromDisk({ space: localSpace, vcsPath });
+            const indexIbGib = await getB2tFSIndexIbGib({ space: localSpace, metaspace });
             iReckon(lc, Boolean(indexIbGib?.data?.staged_item && indexIbGib.data.staged_item.length > 0)).isGonnaBeTrue();
             iReckon(lc, indexIbGib?.rel8ns?.staged_item).isGonnaBeFalsy();
 
@@ -266,6 +268,8 @@ await respecfully(lc, `vcs status and vcs add Command Handlers`, async () => {
             });
 
             iReckon(lc, addRes.stagedPaths).includes('src/utils/math.js');
+        } catch (error) {
+            iReckon(lc, true).asTo(extractErrorMsg(error)).isGonnaBeFalse();
         } finally {
             await fs.rm(testDir, { recursive: true, force: true });
         }

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

@@ -1,6 +1,6 @@
 /**
  * @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`.
  */
@@ -31,7 +31,7 @@ export async function readVcsIndexProjectionFromDisk({
     const lc = `${lcFile}[${readVcsIndexProjectionFromDisk.name}]`;
     try {
         if (logalot) {
-            console.log(`${lc} starting... (I: 7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b)`);
+            console.log(`${lc} starting... (I: genuuid)`);
         }
 
         if (!vcsPath) {
@@ -60,11 +60,11 @@ export async function readVcsIndexProjectionFromDisk({
         const indexIbGib = ibgibs?.at(0) as B2tFSIndexIbGib_V1;
         return indexIbGib;
     } catch (error) {
-        console.error(`${lc} ${extractErrorMsg(error)} (E: 8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c)`);
+        console.error(`${lc} ${extractErrorMsg(error)} (E: genuuid)`);
         throw error;
     } finally {
         if (logalot) {
-            console.log(`${lc} complete. (I: 9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d)`);
+            console.log(`${lc} complete. (I: genuuid)`);
         }
     }
 }
@@ -82,7 +82,7 @@ export async function writeVcsIndexProjectionToDisk({
     const lc = `${lcFile}[${writeVcsIndexProjectionToDisk.name}]`;
     try {
         if (logalot) {
-            console.log(`${lc} starting... (I: 3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b)`);
+            console.log(`${lc} starting... (I: 06da189dd09843652865d2c82e415826)`);
         }
 
         await fs.mkdir(vcsPath, { recursive: true });
@@ -93,7 +93,7 @@ export async function writeVcsIndexProjectionToDisk({
             _comment: 'STRICTLY READ-ONLY PROJECTION GENERATED FROM B2TFSINDEXIBGIB_V1 IN LOCALSPACE',
             indexAddr,
             spaceId: indexIbGib.data?.mySpaceId,
-            activeBranch: indexIbGib.data?.activeBranch || 'main',
+            activeBranchName: indexIbGib.data?.activeBranchName || 'main',
             stagedCount: (indexIbGib.data?.staged_item || []).length,
             stagedPaths: indexIbGib.data?.stagedPaths || {},
             updatedAt: new Date().toISOString(),
@@ -102,11 +102,11 @@ export async function writeVcsIndexProjectionToDisk({
         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)`);
+        console.error(`${lc} ${extractErrorMsg(error)} (E: genuuid)`);
         throw error;
     } finally {
         if (logalot) {
-            console.log(`${lc} complete. (I: 5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d)`);
+            console.log(`${lc} complete. (I: genuuid)`);
         }
     }
 }