@ibgib/vcs-gib 0.0.32 → 0.0.34

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

@@ -0,0 +1,87 @@
+/**
+ * @module branch-cmd
+ *
+ * CLI command handler for `vcs branch [branchName]`.
+ * Delegates to executeVcsBranch and formats terminal output.
+ */
+
+import path from 'node:path';
+
+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 = `[branch-cmd]`;
+const logalot = GLOBAL_LOG_A_LOT;
+
+export interface BranchInfo {
+    name: string;
+    isActive: boolean;
+    addr: string;
+    rootItemAddr?: string;
+}
+
+export interface BranchCmdOpts {
+    branchName?: string;
+    itemPath?: string;
+    targetDir?: string;
+    vcsFolderName?: string;
+    quiet?: boolean;
+}
+
+export interface BranchCmdResult {
+    branches: BranchInfo[];
+    createdBranchName?: string;
+    createdBranchAddr?: string;
+}
+
+export async function executeBranchCmd({
+    branchName,
+    itemPath,
+    targetDir = process.cwd(),
+    vcsFolderName = '.vcsgib',
+    quiet = false,
+}: BranchCmdOpts = {}): Promise<BranchCmdResult> {
+    const lc = `${lcFile}[${executeBranchCmd.name}]`;
+    try {
+        if (logalot) { console.log(`${lc} starting... (I: genuuid)`); }
+
+        const absTargetDir = path.resolve(targetDir);
+        const { repo, } = await openVcsRepository({ targetDir: absTargetDir, vcsFolderName });
+
+        const branchRes = await repo.branch({
+            branchName,
+            itemPath,
+            targetDir: absTargetDir,
+        });
+
+        const branches: BranchInfo[] = branchRes.branches.map(b => ({
+            name: b.name,
+            isActive: b.isActive,
+            addr: b.branchAddr || '',
+            rootItemAddr: b.rootItemAddr,
+        }));
+
+        if (!quiet) {
+            if (!branchName) {
+                for (const b of branches) {
+                    const prefix = b.isActive ? '* ' : '  ';
+                    console.log(`${prefix}${b.name}`);
+                }
+            } else {
+                console.log(`Created branch '${branchRes.createdBranchName}'`);
+            }
+        }
+
+        return {
+            branches,
+            createdBranchName: branchRes.createdBranchName,
+            createdBranchAddr: branchRes.createdBranchAddr,
+        };
+    } 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-checkout-cmd.mts

@@ -0,0 +1,72 @@
+/**
+ * @module checkout-cmd
+ *
+ * CLI command handler for `vcs checkout <branchName>`.
+ * Thin facade delegating to VcsRepository.checkout.
+ */
+
+import path from 'node:path';
+
+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 = `[checkout-cmd]`;
+const logalot = GLOBAL_LOG_A_LOT;
+
+export interface CheckoutCmdOpts {
+    branchName?: string;
+    force?: boolean;
+    targetDir?: string;
+    vcsFolderName?: string;
+    quiet?: boolean;
+}
+
+export interface CheckoutCmdResult {
+    previousBranch: string;
+    currentBranch: string;
+    worktreePath: string;
+}
+
+export async function executeCheckoutCmd({
+    branchName,
+    force = false,
+    targetDir = process.cwd(),
+    vcsFolderName = '.vcsgib',
+    quiet = false,
+}: CheckoutCmdOpts = {}): Promise<CheckoutCmdResult> {
+    const lc = `${lcFile}[${executeCheckoutCmd.name}]`;
+    try {
+        if (logalot) { console.log(`${lc} starting... (I: genuuid)`); }
+
+        const trimmedBranchName = branchName?.trim();
+        if (!trimmedBranchName) {
+            throw new Error(`Branch name is required for checkout (E: genuuid)`);
+        }
+
+        const absTargetDir = path.resolve(targetDir);
+        const { repo } = await openVcsRepository({ targetDir: absTargetDir, vcsFolderName });
+
+        const checkoutRes = await repo.checkout({
+            branchName: trimmedBranchName,
+            force,
+            targetDir: absTargetDir,
+        });
+
+        if (!quiet) {
+            console.log(`Switched to branch '${checkoutRes.currentBranch}' (I: genuuid)`);
+            console.log(`Worktree path: ${checkoutRes.worktreePath}`);
+        }
+
+        return {
+            previousBranch: checkoutRes.previousBranch,
+            currentBranch: checkoutRes.currentBranch,
+            worktreePath: checkoutRes.worktreePath,
+        };
+    } 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-commit-cmd.mts

@@ -0,0 +1,77 @@
+/**
+ * @module commit-cmd
+ *
+ * CLI command handler for `vcs commit -m <message>`.
+ * Bootstraps workspace projection space and delegates to executeVcsCommit.
+ */
+
+import path from 'node:path';
+
+import { extractErrorMsg } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
+
+import { GLOBAL_LOG_A_LOT } from '../../vcs-gib-constants.mjs';
+import { openVcsRepository } from '../vcs-repo-helper.mjs';
+
+const lcFile = `[commit-cmd]`;
+const logalot = GLOBAL_LOG_A_LOT;
+
+export interface CommitCmdOpts {
+    message?: string;
+    targetDir?: string;
+    vcsFolderName?: string;
+    author?: string;
+    quiet?: boolean;
+}
+
+export interface CommitCmdResult {
+    branchName: string;
+    commitAddr: string;
+    commentAddr?: string;
+    rootItemAddr: string;
+    committedPaths: string[];
+    ingestedCommentsCount: number;
+}
+
+export async function executeCommitCmd({
+    message,
+    targetDir = process.cwd(),
+    vcsFolderName = '.vcsgib',
+    author = 'vcs-user',
+    quiet = false,
+}: CommitCmdOpts = {}): Promise<CommitCmdResult> {
+    const lc = `${lcFile}[${executeCommitCmd.name}]`;
+    try {
+        if (logalot) { console.log(`${lc} starting... (I: genuuid)`); }
+
+        const absTargetDir = path.resolve(targetDir);
+        const { repo } = await openVcsRepository({ targetDir: absTargetDir, vcsFolderName });
+
+        const commitRes = await repo.commit({
+            message,
+            author,
+            targetDir: absTargetDir,
+        });
+
+        if (!quiet) {
+            console.log(`[${commitRes.branchName} ${commitRes.commitAddr.slice(0, 7)}] ${message || '(companion comments committed)'}`);
+            console.log(` ${commitRes.committedPaths.length} file(s) changed`);
+            if (commitRes.ingestedCommentsCount > 0) {
+                console.log(` ${commitRes.ingestedCommentsCount} companion comment(s) attached and merged`);
+            }
+        }
+
+        return {
+            branchName: commitRes.branchName,
+            commitAddr: commitRes.commitAddr,
+            commentAddr: commitRes.commentAddr,
+            rootItemAddr: commitRes.rootItemAddr,
+            committedPaths: commitRes.committedPaths,
+            ingestedCommentsCount: commitRes.ingestedCommentsCount,
+        };
+    } catch (error) {
+        console.error(`${lc} ${extractErrorMsg(error)} (E: 4c453a4e7648a5f6058edf489254c826)`);
+        throw error;
+    } finally {
+        if (logalot) { console.log(`${lc} complete. (I: genuuid)`); }
+    }
+}

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

@@ -1,6 +1,6 @@
 /**
  * @module generate-comment-cmd
- * 
+ *
  * Command handler for `vcs generate-comment` (synonyms: `gen-comment`, `gen-msg`, `gcomm`, `gmsg`).
  * Scans repository status or target paths and creates `.ib.<file>.md` or `.ib.<topic>.md` companion metadata files.
  */
@@ -12,6 +12,7 @@ import { extractErrorMsg } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs
 import { bootstrapVcsMetaspace } from '../../bootstrap/node-bootstrap.mjs';
 import { GLOBAL_LOG_A_LOT } from '../../vcs-gib-constants.mjs';
 import { getRepoStatus } from '@ibgib/core-gib/dist/vcs/status/status-helper.mjs';
+import { getB2tFSIndexIbGib } from '@ibgib/core-gib/dist/vcs/index/index-helper.mjs';
 import { readVcsIndexProjectionFromDisk } from '../vcs-projection-helper.mjs';
 
 const lcFile = `[generate-comment-cmd]`;
@@ -41,7 +42,7 @@ export async function executeGenerateCommentCmd({
 
     try {
         if (logalot) {
-            console.log(`${lc} starting... (I: 8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e)`);
+            console.log(`${lc} starting... (I: genuuid)`);
         }
 
         const absTargetDir = path.resolve(targetDir);
@@ -55,10 +56,11 @@ export async function executeGenerateCommentCmd({
         try {
             await fs.access(vcsPath);
         } catch {
-            throw new Error(`Not an ibgib repository (directory ${vcsPath} does not exist) (E: 9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f)`);
+            throw new Error(`Not an ibgib repository (directory ${vcsPath} does not exist) (E: genuuid)`);
         }
 
-        const indexIbGib = await readVcsIndexProjectionFromDisk({ vcsPath, space: localSpace });
+        const indexIbGib = (await getB2tFSIndexIbGib({ space: localSpace, metaspace }))
+            || (await readVcsIndexProjectionFromDisk({ vcsPath, space: localSpace }));
 
         const statusRes = await getRepoStatus({
             metaspace,
@@ -165,11 +167,11 @@ export async function executeGenerateCommentCmd({
             skippedFiles,
         };
     } catch (error) {
-        console.error(`${lc} ${extractErrorMsg(error)} (E: 0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a)`);
+        console.error(`${lc} ${extractErrorMsg(error)} (E: genuuid)`);
         throw error;
     } finally {
         if (logalot) {
-            console.log(`${lc} complete. (I: 1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b)`);
+            console.log(`${lc} complete. (I: genuuid)`);
         }
     }
 }

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

@@ -0,0 +1,78 @@
+/**
+ * @module init-cmd
+ *
+ * CLI command handler for `vcs init [targetDir]`.
+ * Bootstraps Node environment, creates disk directories, and delegates to executeVcsInit.
+ */
+
+import path from 'node:path';
+import fs from 'node:fs/promises';
+
+import { extractErrorMsg } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
+import { VcsRepository } from '@ibgib/core-gib/dist/vcs/vcs-repository.mjs';
+import { B2TFS_BRANCH_DEFAULT_NAME } from '@ibgib/core-gib/dist/vcs/branch/branch-constants.mjs';
+
+import { GLOBAL_LOG_A_LOT } from '../../vcs-gib-constants.mjs';
+import { bootstrapVcsMetaspace } from '../../bootstrap/node-bootstrap.mjs';
+import { writeVcsIndexProjectionToDisk } from '../vcs-projection-helper.mjs';
+
+const lcFile = `[init-cmd]`;
+const logalot = GLOBAL_LOG_A_LOT;
+
+export interface InitCmdOpts {
+    targetDir?: string;
+    vcsFolderName?: string;
+    defaultBranchName?: string;
+    quiet?: boolean;
+}
+
+export interface InitCmdResult {
+    vcsPath: string;
+    spaceId: string;
+    branchName: string;
+    rootItemIb: string;
+}
+
+export async function executeInitCmd({
+    targetDir = process.cwd(),
+    vcsFolderName = '.vcsgib',
+    defaultBranchName = B2TFS_BRANCH_DEFAULT_NAME,
+    quiet = false,
+}: InitCmdOpts = {}): Promise<InitCmdResult> {
+    const absTargetDir = path.resolve(targetDir);
+    const vcsPath = path.join(absTargetDir, vcsFolderName);
+
+    // 1. Ensure target directory exists
+    await fs.mkdir(absTargetDir, { recursive: true });
+
+    // 2. Bootstrap Metaspace and localSpace (creates .vcsgib on disk)
+    const { metaspace, localSpace } = await bootstrapVcsMetaspace({
+        repoPath: absTargetDir,
+        vcsFolderName,
+        defaultSpaceName: `vcs_${path.basename(absTargetDir).replace(/[^a-zA-Z0-9_\-]/g, '_')}`,
+    });
+
+    // 3. Facade instantiation and domain init
+    const repo = new VcsRepository({
+        metaspace,
+        localSpace,
+        repoRoot: absTargetDir,
+        vcsFolderName,
+    });
+
+    const initRes = await repo.init({
+        rootFolderName: path.basename(absTargetDir) || 'root',
+        branchName: defaultBranchName,
+    });
+
+    if (!quiet) {
+        console.log(`Initialized empty ibgib repository in ${vcsPath} (branch: ${defaultBranchName})`);
+    }
+
+    return {
+        vcsPath,
+        spaceId: initRes.spaceId,
+        branchName: initRes.branchName,
+        rootItemIb: initRes.rootItem.ib,
+    };
+}

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

@@ -1,6 +1,6 @@
 /**
  * @module log-cmd
- * 
+ *
  * CLI command handler for `vcs log`.
  * Delegates to executeVcsLog and formats console output.
  */
@@ -9,13 +9,10 @@ import path from 'node:path';
 import fs from 'node:fs/promises';
 
 import { extractErrorMsg } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
-import { executeVcsLog } from '@ibgib/core-gib/dist/vcs/commands/log-cmd.mjs';
-import { resolveContextualBranchName } from '@ibgib/core-gib/dist/vcs/branch/branch-helper.mjs';
+// import { getSpaceIdFromIb } from '@ibgib/core-gib/dist/witness/space/metaspace/metaspace-innerspace/metaspace-innerspace-helper.mjs';
 
-import { bootstrapVcsMetaspace } from '../../bootstrap/node-bootstrap.mjs';
-import { getOrCreateBranchSpace } from '@ibgib/node-gib/dist/vcs/branch-space-helper.mjs';
-import { readVcsIndexProjectionFromDisk } from '../vcs-projection-helper.mjs';
 import { GLOBAL_LOG_A_LOT } from '../../vcs-gib-constants.mjs';
+import { openVcsRepository } from '../vcs-repo-helper.mjs';
 
 const lcFile = `[log-cmd]`;
 const logalot = GLOBAL_LOG_A_LOT;
@@ -57,50 +54,20 @@ export async function executeLogCmd({
 
     try {
         if (logalot) {
-            console.log(`${lc} starting executeLogCmd (I: 1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e)`);
+            console.log(`${lc} starting executeLogCmd (I: genuuid)`);
         }
 
         const absTargetDir = path.resolve(targetDir);
+        const { repo } = await openVcsRepository({ targetDir: absTargetDir, vcsFolderName });
+        const indexIbGib = await repo.getIndexIbGib();
+        const activeBranchSpace = await repo.getActiveBranchSpace(indexIbGib);
 
-        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: 2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f)`);
-        }
-
-        // 1. Fetch authoritative B2tFSIndexIbGib_V1 directly from localSpace
-        const indexIbGib = await readVcsIndexProjectionFromDisk({ vcsPath, space: localSpace });
-        if (!indexIbGib) {
-            throw new Error(`Repository index B2tFSIndexIbGib_V1 not found in localSpace (E: 3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a)`);
-        }
-
-        const branchName = resolveContextualBranchName({
-            targetDir: absTargetDir,
-            repoRoot,
-            indexIbGib,
-        });
-
-        // Target active branch space b2s_<activeBranch>
-        const { space: activeSpace } = await getOrCreateBranchSpace({
-            metaspace,
-            vcsPath,
-            branchName,
-        });
-
-        const logRes = await executeVcsLog({
-            metaspace,
-            localSpace,
-            activeBranchSpace: activeSpace,
+        const logRes = await repo.log({
+            activeBranchSpace,
             indexIbGib,
+            // repoRoot, // need this? we need jsdocs on wth repoRoot is
             filePath,
             allComments,
-            repoRoot,
             targetDir: absTargetDir,
         });
 
@@ -108,7 +75,7 @@ export async function executeLogCmd({
 
         if (!quiet) {
             if (logRes.targetPath) {
-                console.log(`File: ${logRes.targetPath} (branch: ${logRes.branchName}) (I: 6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d)`);
+                console.log(`File: ${logRes.targetPath} (branch: ${logRes.branchName}) (I: genuuid)`);
                 if (commits.length === 0) {
                     console.log('No comments found for this file.');
                 } else {
@@ -119,7 +86,7 @@ export async function executeLogCmd({
                     }
                 }
             } else {
-                console.log(`Branch: ${logRes.branchName} (I: 4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b)`);
+                console.log(`Branch: ${logRes.branchName} (I: genuuid)`);
                 if (commits.length === 0) {
                     console.log('No commits yet.');
                 } else {
@@ -149,11 +116,11 @@ export async function executeLogCmd({
             commits,
         };
     } catch (error) {
-        console.error(`${lc} ${extractErrorMsg(error)} (E: 5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c)`);
+        console.error(`${lc} ${extractErrorMsg(error)} (E: genuuid)`);
         throw error;
     } finally {
         if (logalot) {
-            console.log(`${lc} complete. (I: 6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d)`);
+            console.log(`${lc} complete. (I: genuuid)`);
         }
     }
 }

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

@@ -0,0 +1,99 @@
+/**
+ * @module merge-cmd
+ *
+ * CLI command handler for `vcs merge <branchName>`.
+ * Merges incoming branch into base branch and delegates to executeVcsMerge.
+ */
+
+import path from 'node:path';
+
+import { extractErrorMsg } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
+import { getOrCreateBranchSpace } from '@ibgib/core-gib/dist/vcs/branch/branch-helper.mjs';
+import { getSpaceIdFromIb } from '@ibgib/core-gib/dist/witness/space/metaspace/metaspace-innerspace/metaspace-innerspace-helper.mjs';
+
+import { GLOBAL_LOG_A_LOT } from '../../vcs-gib-constants.mjs';
+import { openVcsRepository } from '../vcs-repo-helper.mjs';
+
+const lcFile = `[merge-cmd]`;
+const logalot = GLOBAL_LOG_A_LOT;
+
+export interface MergeCmdOpts {
+    incomingBranchName?: string;
+    targetDir?: string;
+    vcsFolderName?: string;
+    quiet?: boolean;
+}
+
+export interface MergeCmdResult {
+    baseBranch: string;
+    incomingBranch: string;
+    baseSpaceId: string;
+    incomingSpaceId: string;
+    mergedBranchAddr?: string;
+    worktreePath: string;
+}
+
+export async function executeMergeCmd({
+    incomingBranchName,
+    targetDir = process.cwd(),
+    vcsFolderName = '.vcsgib',
+    quiet = false,
+}: MergeCmdOpts = {}): Promise<MergeCmdResult> {
+    const lc = `${lcFile}[${executeMergeCmd.name}]`;
+    try {
+        if (logalot) {
+            console.log(`${lc} starting... (I: genuuid)`);
+        }
+
+        const trimmedIncomingBranchName = incomingBranchName?.trim();
+        if (!trimmedIncomingBranchName) {
+            throw new Error(`Branch name is required for merge (E: genuuid)`);
+        }
+
+        const absTargetDir = path.resolve(targetDir);
+        const { repo, vcsPath, activeWorktreeDir } =
+            await openVcsRepository({ targetDir: absTargetDir, vcsFolderName });
+
+        // todo: get baseBranchName based off of targetDir?
+        const baseBranchName = await repo.getActiveBranchName();
+
+        const incomingSpaceRes = await getOrCreateBranchSpace({
+            metaspace: repo.metaspace,
+            branchName: trimmedIncomingBranchName,
+        });
+
+        const activeBranchSpace = await repo.getActiveBranchSpace();
+        const activeBranchSpaceId = getSpaceIdFromIb(activeBranchSpace.ib);
+
+        const mergeRes = await repo.merge({
+            baseBranchSpace: activeBranchSpace, // what should this be? always the active one? Or does the working dir determine it? What is absTargetDir?
+            // message,
+            // repoRoot,
+            incomingBranchName: trimmedIncomingBranchName,
+            incomingBranchSpace: incomingSpaceRes.space,
+            targetDir: absTargetDir,
+        });
+
+        if (!quiet) {
+            console.log(`Successfully merged branch '${trimmedIncomingBranchName}' into '${baseBranchName}' (I: genuuid)`);
+            console.log(`  Worktree projection: ${activeWorktreeDir}`);
+        }
+
+
+        return {
+            baseBranch: mergeRes.baseBranch,
+            incomingBranch: mergeRes.incomingBranch,
+            baseSpaceId: activeBranchSpaceId,
+            incomingSpaceId: incomingSpaceRes.spaceId,
+            mergedBranchAddr: mergeRes.mergeCommitAddr,
+            worktreePath: activeWorktreeDir,
+        };
+    } 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-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)`);
+        }
+    }
+}