@ibgib/vcs-gib 0.0.6 → 0.0.17

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

@@ -22,11 +22,13 @@ import { bootstrapVcsMetaspace } from '../../bootstrap/node-bootstrap.mjs';
 import { getOrCreateBranchSpace } from '../../engine/branch/branch-space-helper.mjs';
 import { getB2tFSItemIb } from '../../engine/item/item-atom-helper.mjs';
 import { B2tFSItemIbGib_V1, B2TFS_CHILD_ITEM_REL8N_NAME } from '../../engine/item/item-types.mjs';
-import { getIbGibWithMetaspaceFallback } from '../../engine/item/item-helper.mjs';
+import { getIbGibWithMetaspaceFallback, createB2tFSItemIbGib, evolveB2tFSItemIbGib } from '../../engine/item/item-helper.mjs';
 import { B2tFSBranchIbGib_V1 } from '../../engine/branch/branch-types.mjs';
 import { isPathFiltered, parseFilterFileContent, globToRegExp } from '../../engine/filter/glob-helper.mjs';
 import { getB2tFSIndexIbGib, updateB2tFSIndexIbGib } from '../../engine/index/index-helper.mjs';
 import { B2tFSStagedItemRecord } from '../../engine/index/index-types.mjs';
+import { TransformResult } from '@ibgib/ts-gib/dist/types.mjs';
+import { IbGib_V1 } from '@ibgib/ts-gib/dist/V1/types.mjs';
 import { GLOBAL_LOG_A_LOT } from '../../vcs-gib-constants.mjs';
 
 const lcFile = `[add-cmd]`;
@@ -97,7 +99,7 @@ export async function executeAddCmd({
         }
 
         // Walk active branch graph items to find committed files in snapshot
-        const committedBranchItemsMap = new Map<string, { relPath: string; fileHash?: string; fsType: 'file' | 'folder' }>();
+        const committedBranchItemsMap = new Map<string, { relPath: string; fileHash?: string; fsType: 'file' | 'folder'; item?: B2tFSItemIbGib_V1 }>();
         const branchAddrs = [
             ...(indexIbGib?.rel8ns?.branch || []),
             ...(indexIbGib?.rel8ns?.branch_tjp || []),
@@ -182,7 +184,7 @@ export async function executeAddCmd({
                         throw new Error(`No files matched glob pattern: ${relOrAbs} (E: e23d4c5f6a7b8c9d0e1f2a3b4c5d6e7f)`);
                     }
                 } else {
-                    const fullPath = path.resolve(activeWorktreeDir, relOrAbs);
+                    const fullPath = path.resolve(targetDir, relOrAbs);
                     let stat;
                     try {
                         stat = await fs.stat(fullPath);
@@ -191,6 +193,9 @@ export async function executeAddCmd({
                     }
 
                     const relPath = path.relative(activeWorktreeDir, fullPath).replace(/\\/g, '/');
+                    if (relPath.startsWith('..') || path.isAbsolute(relPath)) {
+                        throw new Error(`Path '${relOrAbs}' is outside of active worktree repository (E: 7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f)`);
+                    }
 
                     if (isPathFiltered({ relativePath: relPath, isDirectory: stat.isDirectory(), filterPatterns })) {
                         continue;
@@ -243,31 +248,36 @@ export async function executeAddCmd({
             await putInSpace({ ibGib: binIbGib, space: activeSpace });
             await metaspace.registerNewIbGib({ ibGib: binIbGib, space: activeSpace });
 
-            // 2. Create B2tFSItemIbGib_V1 candidate graph node
+            // 2. Create or Evolve B2tFSItemIbGib_V1 candidate graph node
             const fileName = path.basename(absFilePath);
-            const fileNameSansExt = path.parse(fileName).name;
-            const fileExt = path.parse(fileName).ext.replace(/^\./, '');
             const nameHash = crypto.createHash('sha256').update(fileName).digest('hex');
 
-            const itemRes = await Factory_V1.firstGen({
-                parentIbGib: ROOT,
-                ib: getB2tFSItemIb('file', fileName, nameHash),
-                data: {
-                    name: fileName,
-                    nameHash,
+            let itemRes: TransformResult<IbGib_V1>;
+            if (committedItem && committedItem.item) {
+                itemRes = await evolveB2tFSItemIbGib({
+                    existingItem: committedItem.item,
+                    dataToUpdate: {
+                        fileHash,
+                    },
+                    rel8nsToUpdate: {
+                        bin: [binAddr],
+                    },
+                });
+            } else {
+                itemRes = await createB2tFSItemIbGib({
                     fsType: 'file',
-                    fileNameSansExt,
-                    fileExt,
-                    fileHash,
-                    fileEncoding: 'utf8',
-                    diffTransactionId: await getUUID(),
-                    uuid: await getUUID(),
-                    classname: 'B2tFSItemIbGib_V1',
-                },
-                rel8ns: {
-                    bin: [binAddr],
-                },
-            });
+                    name: fileName,
+                    data: {
+                        nameHash,
+                        fileHash,
+                        fileEncoding: 'utf8',
+                    },
+                    rel8ns: {
+                        bin: [binAddr],
+                    },
+                });
+            }
+
             const itemIbGib = itemRes.newIbGib as B2tFSItemIbGib_V1;
             const itemAddr = getIbGibAddr({ ibGib: itemIbGib });
             await persistTransformResult({ resTransform: itemRes, space: activeSpace });
@@ -332,13 +342,13 @@ async function addCmd_walkBranchGraph({
     space: any;
     metaspace?: any;
     currentRelPath: string;
-    outMap: Map<string, { relPath: string; fileHash?: string; fsType: 'file' | 'folder' }>;
+    outMap: Map<string, { relPath: string; fileHash?: string; fsType: 'file' | 'folder'; item?: B2tFSItemIbGib_V1 }>;
 }): Promise<void> {
     if (!item || !item.data) { return; }
 
     const { fsType, fileHash } = item.data;
     if (currentRelPath) {
-        outMap.set(currentRelPath, { relPath: currentRelPath, fileHash, fsType });
+        outMap.set(currentRelPath, { relPath: currentRelPath, fileHash, fsType, item });
     }
 
     if (fsType === 'folder') {

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

@@ -319,4 +319,83 @@ await respecfully(lc, `vcs branch and vcs checkout Command Handlers`, async () =
             await fs.rm(testDir, { recursive: true, force: true });
         }
     });
+
+    await ifWe(lc, `branches single file-root item and projects into file-branch worktree on checkout`, async () => {
+        const testDir = path.join(process.cwd(), '.test_branch_checkout_file_root');
+        const vcsFolderName = '.vcsgib_test_bc_file';
+        try {
+            await executeInitCmd({
+                targetDir: testDir,
+                vcsFolderName,
+                quiet: true,
+            });
+
+            // Create nested file structure src/utils/math.js and commit on main
+            const mathRelPath = 'src/utils/math.js';
+            await fs.mkdir(path.join(testDir, 'src', 'utils'), { recursive: true });
+            await fs.writeFile(path.join(testDir, mathRelPath), 'export function add(a, b) { return a + b; }', 'utf8');
+
+            await executeAddCmd({
+                paths: [mathRelPath],
+                targetDir: testDir,
+                vcsFolderName,
+                quiet: true,
+            });
+
+            await executeCommitCmd({
+                message: 'Add math.js',
+                targetDir: testDir,
+                vcsFolderName,
+                quiet: true,
+            });
+
+            // Execute branch command for single file math-opt targeting src/utils/math.js
+            const branchRes = await executeBranchCmd({
+                branchName: 'math-opt',
+                itemPath: mathRelPath,
+                targetDir: testDir,
+                vcsFolderName,
+                quiet: true,
+            });
+
+            iReckon(lc, branchRes.createdBranchName).willEqual('math-opt');
+
+            // Attempt branching uncommitted/non-existent item
+            let uncommittedErr = false;
+            try {
+                await executeBranchCmd({
+                    branchName: 'invalid-file-branch',
+                    itemPath: 'src/utils/non-existent.js',
+                    targetDir: testDir,
+                    vcsFolderName,
+                    quiet: true,
+                });
+            } catch (err: any) {
+                uncommittedErr = true;
+                iReckon(lc, err.message).includes("not found in active branch snapshot");
+            }
+            iReckon(lc, uncommittedErr).isGonnaBeTrue();
+
+            // Execute checkout command for math-opt
+            const checkoutRes = await executeCheckoutCmd({
+                branchName: 'math-opt',
+                targetDir: testDir,
+                vcsFolderName,
+                quiet: true,
+            });
+
+            const expectedWorktree = path.join(testDir, 'b', 'math-opt');
+            iReckon(lc, checkoutRes.worktreePath).willEqual(expectedWorktree);
+
+            // Verify single file projected at expectedWorktree/math.js (my-repo/b/math-opt/math.js)
+            const projectedFilePath = path.join(expectedWorktree, 'math.js');
+            const fileExists = await fs.stat(projectedFilePath).then(s => s.isFile()).catch(() => false);
+            iReckon(lc, fileExists).isGonnaBeTrue();
+
+            const fileContent = await fs.readFile(projectedFilePath, 'utf8');
+            iReckon(lc, fileContent).willEqual('export function add(a, b) { return a + b; }');
+        } finally {
+            await fs.rm(testDir, { recursive: true, force: true });
+        }
+    });
 });

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

@@ -18,7 +18,7 @@ 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 { B2tFSItemIbGib_V1, B2TFS_CHILD_ITEM_REL8N_NAME } 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';
@@ -28,6 +28,7 @@ const logalot = GLOBAL_LOG_A_LOT;
 
 export interface BranchCmdOpts {
     branchName?: string;
+    itemPath?: string;
     targetDir?: string;
     vcsFolderName?: string;
     quiet?: boolean;
@@ -48,6 +49,7 @@ export interface BranchCmdResult {
 
 export async function executeBranchCmd({
     branchName,
+    itemPath,
     targetDir = process.cwd(),
     vcsFolderName = '.vcsgib',
     quiet = false,
@@ -152,7 +154,7 @@ export async function executeBranchCmd({
         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)`);
+            throw new Error(`Cannot find active branch root item to fork branch from (E: 8f7e6d5c4b3a2f1e0d9c8b7a6f5e4d3c)`);
         }
 
         const rootItem = await getIbGibWithMetaspaceFallback({
@@ -165,6 +167,25 @@ export async function executeBranchCmd({
             throw new Error(`Root item node for address '${rootItemAddr}' not found in localSpace (E: 9b8c7d6e5f4a3b2c1d0e9f8a7b6c5d4e)`);
         }
 
+        let targetRootItem: B2tFSItemIbGib_V1 = rootItem;
+        if (itemPath && itemPath.trim().length > 0) {
+            const normalizedItemPath = itemPath.trim().replace(/\\/g, '/').replace(/^\.\//, '');
+            const committedBranchItemsMap = new Map<string, B2tFSItemIbGib_V1>();
+            await executeBranchCmd_walkBranchGraphForItems({
+                item: rootItem,
+                space: activeBranchSpace,
+                metaspace,
+                currentRelPath: '',
+                outMap: committedBranchItemsMap,
+            });
+
+            const targetItemNode = committedBranchItemsMap.get(normalizedItemPath);
+            if (!targetItemNode) {
+                throw new Error(`Item '${itemPath}' not found in active branch snapshot (E: 8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c)`);
+            }
+            targetRootItem = targetItemNode;
+        }
+
         // Instantiate new branch space b2s_<newBranch>
         const { space: newBranchSpace, spaceId: newBranchSpaceId } = await getOrCreateBranchSpace({
             metaspace,
@@ -172,18 +193,18 @@ export async function executeBranchCmd({
             branchName: trimmedBranchName,
         });
 
-        // Populate new branch space from live dependency graph of rootItem
+        // Populate new branch space from live dependency graph of targetRootItem
         await populateBranchSpaceFromGraph({
             sourceSpace: activeBranchSpace,
             targetBranchSpace: newBranchSpace,
-            rootItemIbGib: rootItem,
+            rootItemIbGib: targetRootItem,
             metaspace,
         });
 
         // Create new B2tFSBranchIbGib_V1 branch node inside newBranchSpace
         const newBranchIbGib = await createB2tFSBranchIbGib({
             branchName: trimmedBranchName,
-            rootItem,
+            rootItem: targetRootItem,
             space: newBranchSpace,
             metaspace,
         });
@@ -210,7 +231,7 @@ export async function executeBranchCmd({
         });
 
         if (!quiet) {
-            console.log(`Created branch '${trimmedBranchName}' (I: 0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f)`);
+            console.log(`Created branch '${trimmedBranchName}' (I: 0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5e)`);
         }
 
         // Return updated branch list
@@ -241,3 +262,51 @@ export async function executeBranchCmd({
         }
     }
 }
+
+// #region executeBranchCmd_walkBranchGraphForItems
+async function executeBranchCmd_walkBranchGraphForItems({
+    item,
+    space,
+    metaspace,
+    currentRelPath,
+    outMap,
+}: {
+    item: B2tFSItemIbGib_V1;
+    space: any;
+    metaspace?: any;
+    currentRelPath: string;
+    outMap: Map<string, B2tFSItemIbGib_V1>;
+}): Promise<void> {
+    if (!item || !item.data) { return; }
+
+    const { fsType } = item.data;
+
+    if (currentRelPath) {
+        outMap.set(currentRelPath, item);
+    }
+
+    if (fsType === 'folder') {
+        const childAddrs = item.rel8ns?.[B2TFS_CHILD_ITEM_REL8N_NAME] || [];
+        for (const childAddr of childAddrs) {
+            const childItem = await getIbGibWithMetaspaceFallback({
+                addr: childAddr,
+                space,
+                metaspace,
+            }) as B2tFSItemIbGib_V1;
+
+            if (childItem && childItem.data) {
+                const childRelPath = currentRelPath
+                    ? `${currentRelPath}/${childItem.data.name}`
+                    : childItem.data.name;
+                await executeBranchCmd_walkBranchGraphForItems({
+                    item: childItem,
+                    space,
+                    metaspace,
+                    currentRelPath: childRelPath,
+                    outMap,
+                });
+            }
+        }
+    }
+}
+// #endregion executeBranchCmd_walkBranchGraphForItems

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

@@ -49,7 +49,7 @@ export async function executeCheckoutCmd({
     const lc = `${lcFile}[${executeCheckoutCmd.name}]`;
     try {
         if (logalot) {
-            console.log(`${lc} starting... (I: 3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c)`);
+            console.log(`${lc} starting... (I: 3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8e)`);
         }
 
         const trimmedBranchName = branchName?.trim();
@@ -68,7 +68,7 @@ export async function executeCheckoutCmd({
         try {
             await fs.access(vcsPath);
         } catch {
-            throw new Error(`Not an ibgib repository (directory ${vcsPath} does not exist) (E: 5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e)`);
+            throw new Error(`Not an ibgib repository (directory ${vcsPath} does not exist) (E: 5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0e)`);
         }
 
         // 1. Fetch authoritative repository index from localSpace
@@ -152,7 +152,9 @@ export async function executeCheckoutCmd({
 
         await fs.mkdir(worktreePath, { recursive: true });
 
-        // Retrieve root item and project child items via writeB2tFSItemToFS
+        // Retrieve root item and project branch snapshot onto worktree subfolder:
+        // If rootItem is a single file, write it directly to worktreePath (my-repo/b/<branchName>/<fileName>).
+        // If rootItem is a folder, write child items into worktreePath.
         const rootItem = await getIbGibWithMetaspaceFallback({
             addr: rootItemAddr,
             space: targetBranchSpace,
@@ -160,21 +162,30 @@ export async function executeCheckoutCmd({
         }) as B2tFSItemIbGib_V1;
 
         if (rootItem) {
-            const childAddrs = rootItem.rel8ns?.[B2TFS_CHILD_ITEM_REL8N_NAME] || [];
-            for (const childAddr of childAddrs) {
-                const childItem = await getIbGibWithMetaspaceFallback({
-                    addr: childAddr,
+            if (rootItem.data?.fsType === 'file') {
+                await writeB2tFSItemToFS({
+                    item: rootItem,
+                    destPath: worktreePath,
                     space: targetBranchSpace,
                     metaspace,
-                }) as B2tFSItemIbGib_V1;
-
-                if (childItem) {
-                    await writeB2tFSItemToFS({
-                        item: childItem,
-                        destPath: worktreePath,
+                });
+            } else {
+                const childAddrs = rootItem.rel8ns?.[B2TFS_CHILD_ITEM_REL8N_NAME] || [];
+                for (const childAddr of childAddrs) {
+                    const childItem = await getIbGibWithMetaspaceFallback({
+                        addr: childAddr,
                         space: targetBranchSpace,
                         metaspace,
-                    });
+                    }) as B2tFSItemIbGib_V1;
+
+                    if (childItem) {
+                        await writeB2tFSItemToFS({
+                            item: childItem,
+                            destPath: worktreePath,
+                            space: targetBranchSpace,
+                            metaspace,
+                        });
+                    }
                 }
             }
         }

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

@@ -24,11 +24,13 @@ import { bootstrapVcsMetaspace } from '../../bootstrap/node-bootstrap.mjs';
 import { getOrCreateBranchSpace } from '../../engine/branch/branch-space-helper.mjs';
 import { getB2tFSItemIb } from '../../engine/item/item-atom-helper.mjs';
 import { B2tFSItemIbGib_V1, B2TFS_CHILD_ITEM_REL8N_NAME } from '../../engine/item/item-types.mjs';
-import { getIbGibWithMetaspaceFallback } from '../../engine/item/item-helper.mjs';
+import { getIbGibWithMetaspaceFallback, createB2tFSItemIbGib, evolveB2tFSItemIbGib } from '../../engine/item/item-helper.mjs';
 import { getB2tFSBranchSpaceName } from '../../engine/branch/branch-helper.mjs';
 import { B2tFSBranchIbGib_V1 } from '../../engine/branch/branch-types.mjs';
 import { getB2tFSIndexIbGib, updateB2tFSIndexIbGib, getSpaceQualifiedIbGibAddr } from '../../engine/index/index-helper.mjs';
 import { B2tFSStagedItemRecord } from '../../engine/index/index-types.mjs';
+import { TransformResult } from '@ibgib/ts-gib/dist/types.mjs';
+import { IbGib_V1 } from '@ibgib/ts-gib/dist/V1/types.mjs';
 import { GLOBAL_LOG_A_LOT } from '../../vcs-gib-constants.mjs';
 
 const lcFile = `[commit-cmd]`;
@@ -244,7 +246,7 @@ async function commitCmd_buildEvolvedRootItem({
     metaspace: any;
     repoName: string;
 }): Promise<{ newRootItem: B2tFSItemIbGib_V1; newRootAddr: string }> {
-    const itemsByRelPath = new Map<string, { itemAddr: string; fsType: 'file' | 'folder' }>();
+    const itemsByRelPath = new Map<string, { itemAddr: string; fsType: 'file' | 'folder'; item?: B2tFSItemIbGib_V1 }>();
 
     if (currentRootAddr) {
         const currentRootItem = await getIbGibWithMetaspaceFallback({
@@ -328,27 +330,34 @@ async function commitCmd_buildEvolvedRootItem({
         }
 
         const folderName = folderRelPath ? path.basename(folderRelPath) : repoName;
-        const diffTxId = await getUUID();
         const nameHash = crypto.createHash('sha256').update(folderName).digest('hex');
 
-        const rel8ns: Record<string, string[]> = {};
-        if (childAddrs.length > 0) {
-            rel8ns[B2TFS_CHILD_ITEM_REL8N_NAME] = childAddrs;
-        }
+        const existingFolderRec = itemsByRelPath.get(folderRelPath);
 
-        const folderRes = await Factory_V1.firstGen({
-            parentIbGib: ROOT,
-            ib: getB2tFSItemIb('folder', folderName, nameHash),
-            data: {
-                name: folderName,
-                nameHash,
+        let folderRes: TransformResult<IbGib_V1>;
+
+        if (existingFolderRec && existingFolderRec.item) {
+            const oldChildAddrs = existingFolderRec.item.rel8ns?.[B2TFS_CHILD_ITEM_REL8N_NAME] || [];
+            const toRemoveChildAddrs = oldChildAddrs.filter(a => !childAddrs.includes(a));
+
+            folderRes = await evolveB2tFSItemIbGib({
+                existingItem: existingFolderRec.item,
+                dataToUpdate: {
+                    nameHash,
+                },
+                rel8nsToUpdate: childAddrs.length > 0 ? { [B2TFS_CHILD_ITEM_REL8N_NAME]: childAddrs } : undefined,
+                rel8nsToRemove: toRemoveChildAddrs.length > 0 ? { [B2TFS_CHILD_ITEM_REL8N_NAME]: toRemoveChildAddrs } : undefined,
+            });
+        } else {
+            folderRes = await createB2tFSItemIbGib({
                 fsType: 'folder',
-                diffTransactionId: diffTxId,
-                uuid: await getUUID(),
-                classname: 'B2tFSItemIbGib_V1',
-            },
-            rel8ns,
-        });
+                name: folderName,
+                data: {
+                    nameHash,
+                },
+                rel8ns: childAddrs.length > 0 ? { [B2TFS_CHILD_ITEM_REL8N_NAME]: childAddrs } : undefined,
+            });
+        }
 
         const folderItem = folderRes.newIbGib as B2tFSItemIbGib_V1;
         const folderAddr = getIbGibAddr({ ibGib: folderItem });
@@ -383,16 +392,14 @@ async function commitCmd_walkBranchGraph({
     space: any;
     metaspace?: any;
     currentRelPath: string;
-    outMap: Map<string, { itemAddr: string; fsType: 'file' | 'folder' }>;
+    outMap: Map<string, { itemAddr: string; fsType: 'file' | 'folder'; item?: B2tFSItemIbGib_V1 }>;
 }): Promise<void> {
     if (!item || !item.data) { return; }
 
     const { fsType } = item.data;
     const itemAddr = getIbGibAddr({ ibGib: item });
 
-    if (currentRelPath) {
-        outMap.set(currentRelPath, { itemAddr, fsType });
-    }
+    outMap.set(currentRelPath, { itemAddr, fsType, item });
 
     if (fsType === 'folder') {
         const childAddrs = item.rel8ns?.[B2TFS_CHILD_ITEM_REL8N_NAME] || [];

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

@@ -0,0 +1,128 @@
+/**
+ * @module reset-cmd
+ * 
+ * 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 { putInSpace } from '@ibgib/core-gib/dist/witness/space/space-helper.mjs';
+
+import { bootstrapVcsMetaspace } from '../../bootstrap/node-bootstrap.mjs';
+import { getOrCreateBranchSpace } from '../../engine/branch/branch-space-helper.mjs';
+import { getB2tFSIndexIbGib, unstagePathsFromIndex } from '../../engine/index/index-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: 1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d)`);
+        }
+
+        const absTargetDir = path.resolve(targetDir);
+
+        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: 2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b)`);
+        }
+
+        // Retrieve authoritative B2tFSIndexIbGib_V1 from space
+        const indexIbGib = await getB2tFSIndexIbGib({ space: localSpace, vcsPath });
+        if (!indexIbGib) {
+            throw new Error(`Repository not initialized. Run 'vcs init' first. (E: 3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b)`);
+        }
+
+        const activeBranch = indexIbGib.data?.activeBranch || 'main';
+        const activeWorktreeDir = activeBranch === 'main' ? repoRoot : path.join(repoRoot, 'b', activeBranch);
+
+        const { space: activeSpace } = await getOrCreateBranchSpace({
+            metaspace,
+            vcsPath,
+            branchName: activeBranch,
+        });
+
+        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 unstageRes = await unstagePathsFromIndex({
+            indexIbGib,
+            paths,
+            targetDir,
+            activeWorktreeDir,
+            vcsPath,
+            space: activeSpace,
+            metaspace,
+            all,
+        });
+
+        if (localSpace !== activeSpace) {
+            await putInSpace({ space: localSpace, ibGib: unstageRes.updatedIndex });
+        }
+
+        if (!quiet) {
+            for (const unstagedPath of unstageRes.unstagedPaths) {
+                console.log(`unstaged: ${unstagedPath}`);
+            }
+        }
+
+        const finalStagedCount = Object.keys(unstageRes.updatedIndex.data?.stagedPaths || {}).length;
+        return {
+            unstagedPaths: unstageRes.unstagedPaths,
+            stagedCount: finalStagedCount,
+        };
+    } catch (error) {
+        console.error(`${lc} ${extractErrorMsg(error)} (E: 4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b)`);
+        throw error;
+    } finally {
+        if (logalot) {
+            console.log(`${lc} complete. (I: 5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c)`);
+        }
+    }
+}