@ibgib/vcs-gib 0.0.30 → 0.0.33

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

@@ -0,0 +1,94 @@
+/**
+ * @module reset-cmd
+ *
+ * CLI command handler for `vcs reset [path...]`.
+ * Unstages specified files (or all files) from active branch index in localSpace.
+ */
+
+import path from 'node:path';
+import fs from 'node:fs/promises';
+
+import { extractErrorMsg } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
+import { promptForConfirm } from '@ibgib/helper-gib/dist/helpers/node-helper.mjs';
+import { openVcsRepository } from '../vcs-repo-helper.mjs';
+import { GLOBAL_LOG_A_LOT } from '../../vcs-gib-constants.mjs';
+
+const lcFile = `[reset-cmd]`;
+const logalot = GLOBAL_LOG_A_LOT;
+
+export interface ResetCmdOpts {
+    paths?: string[];
+    targetDir?: string;
+    vcsFolderName?: string;
+    all?: boolean;
+    yes?: boolean;
+    force?: boolean;
+    quiet?: boolean;
+}
+
+export interface ResetCmdResult {
+    unstagedPaths: string[];
+    stagedCount: number;
+}
+
+export async function executeResetCmd({
+    paths = [],
+    targetDir = process.cwd(),
+    vcsFolderName = '.vcsgib',
+    all = false,
+    yes = false,
+    force = false,
+    quiet = false,
+}: ResetCmdOpts = {}): Promise<ResetCmdResult> {
+    const lc = `${lcFile}[${executeResetCmd.name}]`;
+    try {
+        if (logalot) {
+            console.log(`${lc} starting... (I: genuuid)`);
+        }
+
+        const absTargetDir = path.resolve(targetDir);
+        const { repo, activeWorktreeDir } = await openVcsRepository({ targetDir: absTargetDir, vcsFolderName });
+
+        const indexIbGib = await repo.getIndexIbGib();
+        const activeBranchSpace = await repo.getActiveBranchSpace(indexIbGib);
+
+        const skipPrompt = yes || force || quiet || !process.stdin.isTTY;
+        if (!skipPrompt) {
+            const confirmed = await promptForConfirm({ msg: 'Unstage specified files from index?' });
+            if (!confirmed) {
+                if (!quiet) {
+                    console.log('Operation cancelled.');
+                }
+                const stagedCount = Object.keys(indexIbGib.data.stagedPaths || {}).length;
+                return { unstagedPaths: [], stagedCount };
+            }
+        }
+
+        const resetRes = await repo.reset({
+            activeBranchSpace,
+            indexIbGib,
+            paths,
+            all,
+            targetDir: absTargetDir,
+            activeWorktreeDir,
+        });
+
+        if (!quiet) {
+            for (const unstagedPath of resetRes.unstagedPaths) {
+                console.log(`unstaged: ${unstagedPath}`);
+            }
+        }
+
+        return {
+            unstagedPaths: resetRes.unstagedPaths,
+            stagedCount: resetRes.stagedCount,
+        };
+    } catch (error) {
+        console.error(`${lc} ${extractErrorMsg(error)} (E: genuuid)`);
+        throw error;
+    } finally {
+        if (logalot) {
+            console.log(`${lc} complete. (I: genuuid)`);
+        }
+    }
+}

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/cli-status-cmd.mts

@@ -0,0 +1,131 @@
+/**
+ * @module status-cmd
+ * 
+ * CLI command handler for `vcs status`.
+ * Compares physical workspace state against active branch snapshot tip and in-band index staging area.
+ */
+
+import path from 'node:path';
+
+import { extractErrorMsg } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
+import { VcsStatusItem, PendingCommentInfo } from '@ibgib/core-gib/dist/vcs/status/status-helper.mjs';
+import { openVcsRepository } from '../vcs-repo-helper.mjs';
+import { GLOBAL_LOG_A_LOT } from '../../vcs-gib-constants.mjs';
+
+const lcFile = `[status-cmd]`;
+const logalot = GLOBAL_LOG_A_LOT;
+
+export { VcsStatusItem, PendingCommentInfo };
+
+export interface StatusCmdResult {
+    branchName: string;
+    staged: VcsStatusItem[];
+    modified: VcsStatusItem[];
+    deleted: VcsStatusItem[];
+    untracked: VcsStatusItem[];
+    pendingComments: PendingCommentInfo[];
+}
+
+export interface StatusCmdOpts {
+    targetDir?: string;
+    vcsFolderName?: string;
+    quiet?: boolean;
+    comments?: boolean;
+}
+
+export async function executeStatusCmd({
+    targetDir = process.cwd(),
+    vcsFolderName = '.vcsgib',
+    quiet = false,
+    comments = false,
+}: StatusCmdOpts = {}): Promise<StatusCmdResult> {
+    const lc = `${lcFile}[${executeStatusCmd.name}]`;
+
+    try {
+        if (logalot) {
+            console.log(`${lc} starting executeStatusCmd (I: 7a8b9c10d11e12f13a14b15c16d17e18)`);
+        }
+
+        const absTargetDir = path.resolve(targetDir);
+        const { repo } = await openVcsRepository({ targetDir: absTargetDir, vcsFolderName });
+
+        const statusRes = await repo.status({
+            targetDir: absTargetDir,
+        });
+
+        const { staged, modified, deleted, untracked, pendingComments } = statusRes;
+
+        const commentsByTarget = new Map<string, PendingCommentInfo[]>();
+        for (const c of pendingComments) {
+            const list = commentsByTarget.get(c.targetRelPath) || [];
+            list.push(c);
+            commentsByTarget.set(c.targetRelPath, list);
+        }
+
+        if (!quiet) {
+            console.log(`On branch ${statusRes.branchName} (I: 5e6f7a8b9c10d11e12f13a14b15c16d1)`);
+
+            if (staged.length === 0 && modified.length === 0 && deleted.length === 0 && untracked.length === 0 && pendingComments.length === 0) {
+                console.log('nothing to commit, working tree clean');
+            } else {
+                if (staged.length > 0) {
+                    console.log('\nChanges to be committed:');
+                    console.log('  (use "vcs reset <file>..." to unstage)');
+                    for (const item of staged) {
+                        const typePrefix = item.fsType === 'folder' ? 'directory: ' : '';
+                        console.log(`\tnew file:   ${typePrefix}${item.path}`);
+                    }
+                }
+
+                if (modified.length > 0 || deleted.length > 0) {
+                    console.log('\nChanges not staged for commit:');
+                    console.log('  (use "vcs add <file>..." to update what will be committed)');
+                    console.log('  (use "vcs restore <file>..." to discard changes in working directory)');
+                    for (const item of modified) {
+                        console.log(`\tmodified:   ${item.path}`);
+                    }
+                    for (const item of deleted) {
+                        console.log(`\tdeleted:    ${item.path}`);
+                    }
+                }
+
+                if (untracked.length > 0) {
+                    console.log('\nUntracked files:');
+                    console.log('  (use "vcs add <file>..." to include in what will be committed)');
+                    for (const item of untracked) {
+                        const suffix = item.fsType === 'folder' ? '/' : '';
+                        console.log(`\t${item.path}${suffix}`);
+                    }
+                }
+
+                if (pendingComments.length > 0) {
+                    console.log('\nPending companion comments:');
+                    console.log('  (will be attached to items upon "vcs commit")');
+                    for (const comment of pendingComments) {
+                        const targetLabel = comment.targetRelPath ? comment.targetRelPath : '(root)';
+                        console.log(`\tcomment on [${targetLabel}]: ${comment.commentRelPath}`);
+                        if (comments) {
+                            console.log(`\t  Preview: ${comment.content.slice(0, 80).replace(/\n/g, ' ')}...`);
+                        }
+                    }
+                }
+            }
+        }
+
+        return {
+            branchName: statusRes.branchName,
+            staged,
+            modified,
+            deleted,
+            untracked,
+            pendingComments,
+        };
+    } catch (error) {
+        console.error(`${lc} ${extractErrorMsg(error)} (E: 6f7a8b9c10d11e12f13a14b15c16d17e)`);
+        throw error;
+    } finally {
+        if (logalot) {
+            console.log(`${lc} complete. (I: 8a9b10c11d12e13f14a15b16c17d18e1)`);
+        }
+    }
+}

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

@@ -11,23 +11,28 @@ 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 { getB2tFSIndexIbGib } from '../../engine/index/index-helper.mjs';
-import { getOrCreateBranchSpace } from '../../engine/branch/branch-space-helper.mjs';
-import { getIbGibWithMetaspaceFallback } from '../../engine/item/item-helper.mjs';
+import { readVcsIndexProjectionFromDisk } from '../vcs-projection-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 () => {
 
@@ -119,7 +124,7 @@ await respecfully(lc, `vcs commit and vcs log Command Handlers`, async () => {
                 repoPath: testDir,
                 vcsFolderName,
             });
-            const indexAdd = await getB2tFSIndexIbGib({ space: spaceAdd, vcsPath: vcsPathAdd });
+            const indexAdd = await readVcsIndexProjectionFromDisk({ space: spaceAdd, vcsPath: vcsPathAdd });
             iReckon(lc, Boolean(indexAdd?.data?.staged_item && indexAdd.data.staged_item.length > 0)).isGonnaBeTrue();
             iReckon(lc, indexAdd?.rel8ns?.staged_item).isGonnaBeFalsy();
 
@@ -134,7 +139,7 @@ await respecfully(lc, `vcs commit and vcs log Command Handlers`, async () => {
                 repoPath: testDir,
                 vcsFolderName,
             });
-            const indexCommit = await getB2tFSIndexIbGib({ space: spaceCommit, vcsPath: vcsPathCommit });
+            const indexCommit = await readVcsIndexProjectionFromDisk({ space: spaceCommit, vcsPath: vcsPathCommit });
             iReckon(lc, indexCommit?.data?.staged_item).willEqual([]);
             iReckon(lc, indexCommit?.rel8ns?.staged_item).isGonnaBeFalsy();
 
@@ -149,9 +154,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 +441,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,29 +454,73 @@ 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(`\n\n${pretty(allMessages)}\n\n`);
             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 getB2tFSIndexIbGib({ space: metaspace.zeroSpace, vcsPath });
-            const mainBranchAddr = indexIbGib?.rel8ns?.branch?.at(-1) || indexIbGib?.rel8ns?.branch_tjp?.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 }))
+                || (await readVcsIndexProjectionFromDisk({ space: localSpace, vcsPath }));
+            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;
                 }
             }
@@ -482,6 +535,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.
  */
 
@@ -8,21 +8,23 @@ import path from 'node:path';
 import fs from 'node:fs/promises';
 
 import {
-    respecfully, ifWe, iReckon
+    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 { getB2tFSIndexIbGib } from '../../engine/index/index-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 () => {
 
-    await ifWe(lc, `detects untracked files in fresh repository`, async () => {
+    await ifWeMight(lc, `detects untracked files in fresh repository`, async () => {
         const testDir = path.join(process.cwd(), '.test_status_add_1');
         const vcsFolderName = '.vcsgib_test_1';
         try {
@@ -48,7 +50,7 @@ await respecfully(lc, `vcs status and vcs add Command Handlers`, async () => {
         }
     });
 
-    await ifWe(lc, `discovers .vcsgib via upward discovery when executed from a subfolder`, async () => {
+    await ifWeMight(lc, `discovers .vcsgib via upward discovery when executed from a subfolder`, async () => {
         const testDir = path.join(process.cwd(), '.test_status_add_subfolder');
         const vcsFolderName = '.vcsgib_test_subfolder';
         try {
@@ -75,7 +77,7 @@ await respecfully(lc, `vcs status and vcs add Command Handlers`, async () => {
         }
     });
 
-    await ifWe(lc, `skips re-staging unmodified committed files during executeAddCmd with all flag`, async () => {
+    await ifWeMight(lc, `skips re-staging unmodified committed files during executeAddCmd with all flag`, async () => {
         const testDir = path.join(process.cwd(), '.test_status_add_unmodified');
         const vcsFolderName = '.vcsgib_test_unmodified';
         try {
@@ -116,7 +118,7 @@ await respecfully(lc, `vcs status and vcs add Command Handlers`, async () => {
         }
     });
 
-    await ifWe(lc, `stages untracked file via executeAddCmd`, async () => {
+    await ifWeMight(lc, `stages untracked file via executeAddCmd`, async () => {
         const testDir = path.join(process.cwd(), '.test_status_add_2');
         const vcsFolderName = '.vcsgib_test_2';
         try {
@@ -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 getB2tFSIndexIbGib({ 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();
 
@@ -160,7 +162,7 @@ await respecfully(lc, `vcs status and vcs add Command Handlers`, async () => {
         }
     });
 
-    await ifWe(lc, `respects .ibgibignore patterns during status and add`, async () => {
+    await ifWeMight(lc, `respects .ibgibignore patterns during status and add`, async () => {
         const testDir = path.join(process.cwd(), '.test_status_add_3');
         const vcsFolderName = '.vcsgib_test_3';
         try {
@@ -201,7 +203,7 @@ await respecfully(lc, `vcs status and vcs add Command Handlers`, async () => {
         }
     });
 
-    await ifWe(lc, `stages files matching glob pattern with executeAddCmd`, async () => {
+    await ifWeMight(lc, `stages files matching glob pattern with executeAddCmd`, async () => {
         const testDir = path.join(process.cwd(), '.test_status_add_glob');
         const vcsFolderName = '.vcsgib_test_glob';
         try {
@@ -244,7 +246,7 @@ await respecfully(lc, `vcs status and vcs add Command Handlers`, async () => {
         }
     });
 
-    await ifWe(lc, `stages relative file paths correctly when targetDir is a subdirectory`, async () => {
+    await ifWeMight(lc, `stages relative file paths correctly when targetDir is a subdirectory`, async () => {
         const testDir = path.join(process.cwd(), '.test_status_add_subdir');
         const vcsFolderName = '.vcsgib_test_subdir';
         try {
@@ -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 });
         }