@ibgib/vcs-gib 0.0.30 → 0.0.32

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

@@ -1,60 +1,34 @@
 /**
  * @module merge-cmd
- *
- * Command handler for `vcs merge <branchName>`.
- * Merges the incoming branch into the base (active/current) branch using
- * SyncSagaCoordinator sync and 3-way graft merge strategy.
- * Projects merged branch snapshot onto the base branch physical worktree path.
- *
- * ## Terminology (matches standard git usage)
- *
- * * **base** branch / space — the branch currently checked out, the one being
- *   merged INTO (analogous to `ours` / `HEAD` in git)
- * * **incoming** branch / space — the branch whose changes are being merged IN
- *   (analogous to `theirs` / the topic branch in git)
+ * 
+ * CLI command handler for `vcs merge <branchName>`.
+ * Merges incoming branch into base branch and delegates to executeVcsMerge.
  */
 
 import path from 'node:path';
 import fs from 'node:fs/promises';
 
-import { clone, extractErrorMsg } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
-import { getIbGibAddr } from '@ibgib/ts-gib/dist/helper.mjs';
-import { putInSpace, getLatestAddrs, persistTransformResult, registerNewIbGib } from '@ibgib/core-gib/dist/witness/space/space-helper.mjs';
-import { rel8 } from '@ibgib/ts-gib/dist/V1/transforms/rel8.mjs';
-import { SyncSagaCoordinator } from '@ibgib/core-gib/dist/sync/sync-saga-coordinator.mjs';
-import { SyncPeerInnerspace_V1 } from '@ibgib/core-gib/dist/sync/sync-peer/sync-peer-innerspace/sync-peer-innerspace-v1.mjs';
-import { SYNC_PEER_INNERSPACE_DEFAULT_DATA_V1 } from '@ibgib/core-gib/dist/sync/sync-peer/sync-peer-innerspace/sync-peer-innerspace-constants.mjs';
-import { SyncConflictStrategy } from '@ibgib/core-gib/dist/sync/sync-constants.mjs';
-import { GraftPreference } from '@ibgib/core-gib/dist/sync/graft-info/graft-info-types.mjs';
-
+import { extractErrorMsg } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
+import { executeVcsMerge } from '@ibgib/core-gib/dist/vcs/commands/merge-cmd.mjs';
 
 import { bootstrapVcsMetaspace } from '../../bootstrap/node-bootstrap.mjs';
-import { B2tFSBranchIbGib_V1 } from '../../engine/branch/branch-types.mjs';
-import { getOrCreateBranchSpace } from '../../engine/branch/branch-space-helper.mjs';
-import { B2tFSItemIbGib_V1, B2TFS_CHILD_ITEM_REL8N_NAME } from '../../engine/item/item-types.mjs';
-import { writeB2tFSItemToFS, getIbGibWithMetaspaceFallback, reifyB2tFSHierarchy } from '../../engine/item/item-helper.mjs';
-import { getB2tFSIndexIbGib, updateB2tFSIndexIbGib } from '../../engine/index/index-helper.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, writeVcsIndexProjectionToDisk } from '../vcs-projection-helper.mjs';
 import { GLOBAL_LOG_A_LOT } from '../../vcs-gib-constants.mjs';
-import { logBranchState, logItemState, logCheckpoint, logAddr, logAddrs } from '../../test/test-helpers.mjs';
-
 
 const lcFile = `[merge-cmd]`;
 const logalot = GLOBAL_LOG_A_LOT;
 
 export interface MergeCmdOpts {
-    /** The incoming branch name — the branch whose changes will be merged in. */
     incomingBranchName?: string;
     targetDir?: string;
     vcsFolderName?: string;
     quiet?: boolean;
-    /** When true, emit diagnostic checkpoint logging (useful in tests). */
-    diagLog?: boolean;
 }
 
 export interface MergeCmdResult {
-    /** The base (current/active) branch name — merged into. */
     baseBranch: string;
-    /** The incoming branch name — merged from. */
     incomingBranch: string;
     baseSpaceId: string;
     incomingSpaceId: string;
@@ -67,10 +41,8 @@ export async function executeMergeCmd({
     targetDir = process.cwd(),
     vcsFolderName = '.vcsgib',
     quiet = false,
-    diagLog = false,
 }: MergeCmdOpts = {}): Promise<MergeCmdResult> {
     const lc = `${lcFile}[${executeMergeCmd.name}]`;
-    const diag = (label: string) => { if (diagLog) logCheckpoint(`merge-cmd: ${label}`); };
     try {
         if (logalot) {
             console.log(`${lc} starting... (I: 4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f)`);
@@ -96,54 +68,14 @@ export async function executeMergeCmd({
         }
 
         // 1. Fetch authoritative repository index from localSpace
-        const indexIbGib = await getB2tFSIndexIbGib({ space: localSpace, vcsPath });
+        const indexIbGib = await readVcsIndexProjectionFromDisk({ vcsPath, space: localSpace });
         if (!indexIbGib) {
             throw new Error(`Repository index B2tFSIndexIbGib_V1 not found in localSpace (E: 7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c)`);
         }
 
         const baseBranchName = indexIbGib.data?.activeBranch || 'main';
 
-        if (baseBranchName === trimmedIncomingBranch) {
-            throw new Error(`Cannot merge branch '${trimmedIncomingBranch}' into itself (E: 8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d)`);
-        }
-
-        // 2. Fetch all registered branch ibgibs
-        const branchAddrs = [
-            ...(indexIbGib.rel8ns?.branch || []),
-            ...(indexIbGib.rel8ns?.branch_tjp || []),
-        ];
-
-        let branchIbGibs: B2tFSBranchIbGib_V1[] = [];
-        if (branchAddrs.length > 0) {
-            for (const bAddr of branchAddrs) {
-                const bIbGib = await getIbGibWithMetaspaceFallback({
-                    addr: bAddr,
-                    space: localSpace,
-                    metaspace,
-                });
-                if (bIbGib) {
-                    branchIbGibs.push(bIbGib as B2tFSBranchIbGib_V1);
-                }
-            }
-        }
-
-        // Resolve base branch node & incoming branch node
-        const baseBranchIbGib = branchIbGibs.findLast(
-            (b) => b?.data?.name === baseBranchName,
-        );
-        if (!baseBranchIbGib) {
-            throw new Error(`Base branch '${baseBranchName}' not found in repository (E: 9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e)`);
-        }
-
-        const incomingBranchIbGib = branchIbGibs.findLast(
-            (b) => b?.data?.name === trimmedIncomingBranch,
-        );
-
-        if (!incomingBranchIbGib) {
-            throw new Error(`Branch '${trimmedIncomingBranch}' does not exist (E: 0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f)`);
-        }
-
-        // 3. Resolve base branch space & incoming branch space
+        // 2. Resolve base branch space & incoming branch space
         const baseSpaceRes = await getOrCreateBranchSpace({
             metaspace,
             vcsPath,
@@ -158,139 +90,6 @@ export async function executeMergeCmd({
         });
         const incomingSpace = incomingSpaceRes.space;
 
-        await putInSpace({ space: baseSpace, ibGib: baseBranchIbGib });
-        await putInSpace({ space: incomingSpace, ibGib: incomingBranchIbGib });
-
-        // Resolve latest branch tip inside incomingSpace (in case commits occurred on incoming branch)
-        const incomingBranchTjpAddr = incomingBranchIbGib.rel8ns?.tjp?.at(0) || getIbGibAddr({ ibGib: incomingBranchIbGib });
-        const latestIncomingBranchRes = await getLatestAddrs({ space: incomingSpace, addrs: [incomingBranchTjpAddr] });
-        const latestIncomingBranchAddr = (latestIncomingBranchRes?.data as any)?.latestAddrs?.[0] || getIbGibAddr({ ibGib: incomingBranchIbGib });
-
-        const latestIncomingBranchIbGib = (await getIbGibWithMetaspaceFallback({
-            addr: latestIncomingBranchAddr,
-            space: incomingSpace,
-            metaspace,
-        })) as B2tFSBranchIbGib_V1 || incomingBranchIbGib;
-
-        const incomingRootAddr = latestIncomingBranchIbGib.rel8ns?.b2tfs_item?.at(-1);
-
-        if (!incomingRootAddr) {
-            throw new Error(`Incoming branch '${trimmedIncomingBranch}' has no valid root item address (E: 3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e)`);
-        }
-        const incomingRootItem = await getIbGibWithMetaspaceFallback({
-            addr: incomingRootAddr,
-            space: incomingSpace,
-            metaspace,
-        });
-        if (!incomingRootItem) {
-            throw new Error(`Incoming root item '${incomingRootAddr}' not found in incoming space (E: 4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f)`);
-        }
-
-        if (diagLog) {
-            diag('resolving branches & spaces');
-            await logBranchState({ label: 'baseBranch (main)', branchIbGib: baseBranchIbGib, space: baseSpace });
-            await logBranchState({ label: 'incomingBranch (feature-merge)', branchIbGib: incomingBranchIbGib, space: incomingSpace });
-            await logItemState({ label: 'incomingRootItem', itemIbGib: incomingRootItem, space: incomingSpace });
-        }
-
-        // 4. Setup SyncPeerInnerspace and SyncSagaCoordinator syncing incoming branch space into base branch space
-        const peer = new SyncPeerInnerspace_V1(clone(SYNC_PEER_INNERSPACE_DEFAULT_DATA_V1));
-        await peer.initialized;
-        await peer.initializeOpts({
-            localMetaspace: metaspace,
-            localSpace: incomingSpace,
-            receiverSpace: baseSpace,
-            receiverCoordinator: new SyncSagaCoordinator(),
-            receiverMetaspace: metaspace,
-        });
-
-        const senderCoordinator = new SyncSagaCoordinator();
-        const syncSaga = await senderCoordinator.sync({
-            peer,
-            localSpace: incomingSpace,
-            metaspace,
-            domainIbGibs: [incomingRootItem],
-            conflictStrategy: SyncConflictStrategy.optimisticWithLCS,
-            graftPreference: GraftPreference.receiver,
-        });
-
-        await syncSaga.done;
-
-        // 5. Reify the base branch filesystem hierarchy.
-        // After sync, any child timelines (files or subfolders) that were merged/advanced
-        // in baseSpace will have newer tips. reifyB2tFSHierarchy bubbles all updated child tips
-        // up through the folder DAG, evolving parents in-place and returning the newly reified root item.
-        const currentBaseRootItemAddr = baseBranchIbGib.rel8ns?.b2tfs_item?.at(-1);
-        if (!currentBaseRootItemAddr) {
-            throw new Error(`Base branch '${baseBranchName}' has no root item address (E: 6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d)`);
-        }
-
-        const reifyRes = await reifyB2tFSHierarchy({
-            rootItemAddr: currentBaseRootItemAddr,
-            space: baseSpace,
-            metaspace,
-        });
-
-        const reifiedRootItem = reifyRes.reifiedRootItem;
-        const reifiedRootAddr = getIbGibAddr({ ibGib: reifiedRootItem });
-
-        if (diagLog) {
-            diag('after reification');
-            logAddr('currentBaseRootItemAddr', currentBaseRootItemAddr);
-            logAddr('reifiedRootAddr', reifiedRootAddr);
-            console.log(`[merge-cmd] reification hasChanges:`, reifyRes.hasChanges);
-            console.log(`[merge-cmd] reifiedAddrsMap:`, JSON.stringify(reifyRes.reifiedAddrsMap));
-        }
-
-        // 5b. Evolve the base branch ibgib to point at the reified root item tip.
-        // The sync engine does not update branch ibgibs — branches live in
-        // their own space and are never domain ibgibs in the sync. We advance
-        // the branch pointer to the reified root item.
-        let mergedBranchAddr: string = getIbGibAddr({ ibGib: baseBranchIbGib });
-        if (reifyRes.hasChanges && reifiedRootAddr !== currentBaseRootItemAddr) {
-            if (diagLog) {
-                console.log(`[merge-cmd] Evolving base branch: root item changing from ${currentBaseRootItemAddr} -> ${reifiedRootAddr}`);
-            }
-            const resRel8Branch = await rel8({
-                src: baseBranchIbGib,
-                rel8nsToReplaceByAddr: {
-                    b2tfs_item: [{ oldAddr: currentBaseRootItemAddr, newAddr: reifiedRootAddr }],
-                },
-                dna: true,
-                nCounter: true,
-            });
-            const evolvedBranchIbGib = resRel8Branch.newIbGib;
-            await persistTransformResult({ resTransform: resRel8Branch, space: baseSpace });
-            await registerNewIbGib({ ibGib: evolvedBranchIbGib, space: baseSpace });
-            mergedBranchAddr = getIbGibAddr({ ibGib: evolvedBranchIbGib });
-            if (diagLog) {
-                console.log(`[merge-cmd] Base branch evolved to addr: ${mergedBranchAddr}`);
-            }
-        } else {
-            if (diagLog) {
-                console.log(`[merge-cmd] Base branch root item unchanged (${currentBaseRootItemAddr})`);
-            }
-        }
-
-        // Update indexIbGib to reference new merged branch node
-        await updateB2tFSIndexIbGib({
-            space: baseSpace,
-            metaspace,
-            indexIbGib,
-            rel8nsToUpdate: {
-                branch: [mergedBranchAddr],
-            },
-            vcsPath,
-        });
-
-        const mergedRootItemAddr = reifiedRootAddr;
-
-        if (diagLog) {
-            diag('projecting onto disk');
-            logAddr('mergedRootItemAddr', mergedRootItemAddr);
-        }
-
-        // 6. Project merged branch snapshot files onto physical worktree disk
         const isDefaultBranch = baseBranchName === 'main';
         const worktreePath = isDefaultBranch
             ? repoRoot
@@ -298,46 +97,27 @@ export async function executeMergeCmd({
 
         await fs.mkdir(worktreePath, { recursive: true });
 
-        if (mergedRootItemAddr) {
-            const mergedRootItem = await getIbGibWithMetaspaceFallback({
-                addr: mergedRootItemAddr,
-                space: baseSpace,
-                metaspace,
-            }) as B2tFSItemIbGib_V1;
-
-            if (diagLog) {
-                await logItemState({ label: 'mergedRootItem to write', itemIbGib: mergedRootItem, space: baseSpace });
-            }
+        const { space: workspaceSpace } = await getOrCreateWorkspaceProjectionSpace({
+            metaspace,
+            workspaceRoot: worktreePath,
+            vcsFolderName,
+            backingSpace: baseSpace,
+        });
 
-            if (mergedRootItem) {
-                if (mergedRootItem.data?.fsType === 'file') {
-                    await writeB2tFSItemToFS({
-                        item: mergedRootItem,
-                        destPath: worktreePath,
-                        space: baseSpace,
-                        metaspace,
-                    });
-                } else {
-                    const childAddrs = mergedRootItem.rel8ns?.[B2TFS_CHILD_ITEM_REL8N_NAME] || [];
-                    for (const childAddr of childAddrs) {
-                        const childItem = await getIbGibWithMetaspaceFallback({
-                            addr: childAddr,
-                            space: baseSpace,
-                            metaspace,
-                        }) as B2tFSItemIbGib_V1;
+        const mergeRes = await executeVcsMerge({
+            metaspace,
+            localSpace,
+            baseBranchSpace: baseSpace,
+            incomingBranchSpace: incomingSpace,
+            workspaceSpace,
+            indexIbGib,
+            incomingBranchName: trimmedIncomingBranch,
+            repoRoot,
+            targetDir: absTargetDir,
+            vcsFolderName,
+        });
 
-                        if (childItem) {
-                            await writeB2tFSItemToFS({
-                                item: childItem,
-                                destPath: worktreePath,
-                                space: baseSpace,
-                                metaspace,
-                            });
-                        }
-                    }
-                }
-            }
-        }
+        await writeVcsIndexProjectionToDisk({ vcsPath, indexIbGib: mergeRes.updatedIndex });
 
         if (!quiet) {
             console.log(`Successfully merged branch '${trimmedIncomingBranch}' into '${baseBranchName}' (I: 1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a)`);
@@ -345,11 +125,11 @@ export async function executeMergeCmd({
         }
 
         return {
-            baseBranch: baseBranchName,
-            incomingBranch: trimmedIncomingBranch,
+            baseBranch: mergeRes.baseBranch,
+            incomingBranch: mergeRes.incomingBranch,
             baseSpaceId: baseSpaceRes.spaceId,
             incomingSpaceId: incomingSpaceRes.spaceId,
-            mergedBranchAddr,
+            mergedBranchAddr: mergeRes.mergeCommitAddr,
             worktreePath,
         };
     } catch (error) {

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

@@ -1,7 +1,7 @@
 /**
  * @module reset-cmd
  * 
- * Command handler for `vcs reset [path...]`.
+ * CLI command handler for `vcs reset [path...]`.
  * Unstages specified files (or all files) from active branch index in localSpace.
  */
 
@@ -10,11 +10,12 @@ 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 { executeVcsReset } from '@ibgib/core-gib/dist/vcs/commands/reset-cmd.mjs';
+import { resolveContextualBranchName } from '@ibgib/core-gib/dist/vcs/branch/branch-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 { getOrCreateBranchSpace } from '@ibgib/node-gib/dist/vcs/branch-space-helper.mjs';
+import { readVcsIndexProjectionFromDisk, writeVcsIndexProjectionToDisk } from '../vcs-projection-helper.mjs';
 import { GLOBAL_LOG_A_LOT } from '../../vcs-gib-constants.mjs';
 
 const lcFile = `[reset-cmd]`;
@@ -65,12 +66,12 @@ export async function executeResetCmd({
         }
 
         // Retrieve authoritative B2tFSIndexIbGib_V1 from space
-        const indexIbGib = await getB2tFSIndexIbGib({ space: localSpace, vcsPath });
+        const indexIbGib = await readVcsIndexProjectionFromDisk({ vcsPath, space: localSpace });
         if (!indexIbGib) {
             throw new Error(`Repository not initialized. Run 'vcs init' first. (E: 3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b)`);
         }
 
-        const activeBranch = indexIbGib.data?.activeBranch || 'main';
+        const activeBranch = resolveContextualBranchName({ targetDir: absTargetDir, repoRoot, indexIbGib });
         const activeWorktreeDir = activeBranch === 'main' ? repoRoot : path.join(repoRoot, 'b', activeBranch);
 
         const { space: activeSpace } = await getOrCreateBranchSpace({
@@ -91,31 +92,28 @@ export async function executeResetCmd({
             }
         }
 
-        const unstageRes = await unstagePathsFromIndex({
+        const resetRes = await executeVcsReset({
+            metaspace,
+            localSpace,
+            activeBranchSpace: activeSpace,
             indexIbGib,
             paths,
-            targetDir,
-            activeWorktreeDir,
-            vcsPath,
-            space: activeSpace,
-            metaspace,
             all,
+            targetDir: absTargetDir,
+            activeWorktreeDir,
         });
 
-        if (localSpace !== activeSpace) {
-            await putInSpace({ space: localSpace, ibGib: unstageRes.updatedIndex });
-        }
+        await writeVcsIndexProjectionToDisk({ vcsPath, indexIbGib: resetRes.updatedIndex });
 
         if (!quiet) {
-            for (const unstagedPath of unstageRes.unstagedPaths) {
+            for (const unstagedPath of resetRes.unstagedPaths) {
                 console.log(`unstaged: ${unstagedPath}`);
             }
         }
 
-        const finalStagedCount = Object.keys(unstageRes.updatedIndex.data?.stagedPaths || {}).length;
         return {
-            unstagedPaths: unstageRes.unstagedPaths,
-            stagedCount: finalStagedCount,
+            unstagedPaths: resetRes.unstagedPaths,
+            stagedCount: resetRes.stagedCount,
         };
     } catch (error) {
         console.error(`${lc} ${extractErrorMsg(error)} (E: 4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b)`);

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

@@ -1,20 +1,21 @@
 /**
  * @module restore-cmd
  * 
- * Command handler for `vcs restore [path...]`.
- * Restores working tree files from committed branch snapshot, or unstages files if `--staged` is set.
+ * 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 { promptForConfirm } from '@ibgib/helper-gib/dist/helpers/node-helper.mjs';
-import { putInSpace } from '@ibgib/core-gib/dist/witness/space/space-helper.mjs';
+import { executeVcsRestore } from '@ibgib/core-gib/dist/vcs/commands/restore-cmd.mjs';
+import { resolveContextualBranchName } from '@ibgib/core-gib/dist/vcs/branch/branch-helper.mjs';
 
 import { bootstrapVcsMetaspace } from '../../bootstrap/node-bootstrap.mjs';
-import { getOrCreateBranchSpace } from '../../engine/branch/branch-space-helper.mjs';
-import { getB2tFSIndexIbGib, unstagePathsFromIndex, restoreWorktreePathsFromSnapshot } from '../../engine/index/index-helper.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, writeVcsIndexProjectionToDisk } from '../vcs-projection-helper.mjs';
 import { GLOBAL_LOG_A_LOT } from '../../vcs-gib-constants.mjs';
 
 const lcFile = `[restore-cmd]`;
@@ -22,34 +23,36 @@ const logalot = GLOBAL_LOG_A_LOT;
 
 export interface RestoreCmdOpts {
     paths?: string[];
-    targetDir?: string;
-    vcsFolderName?: string;
     staged?: boolean;
     worktree?: boolean;
+    all?: boolean;
     yes?: boolean;
     force?: boolean;
+    targetDir?: string;
+    vcsFolderName?: string;
     quiet?: boolean;
 }
 
 export interface RestoreCmdResult {
-    unstagedPaths?: string[];
-    restoredPaths?: string[];
+    restoredPaths: string[];
+    unstagedPaths: string[];
 }
 
 export async function executeRestoreCmd({
     paths = [],
-    targetDir = process.cwd(),
-    vcsFolderName = '.vcsgib',
     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: 6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1e)`);
+            console.log(`${lc} starting... (I: 1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d)`);
         }
 
         const absTargetDir = path.resolve(targetDir);
@@ -63,93 +66,70 @@ export async function executeRestoreCmd({
         try {
             await fs.access(vcsPath);
         } catch {
-            throw new Error(`Not an ibgib repository (directory ${vcsPath} does not exist) (E: 7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2e)`);
+            throw new Error(`Not an ibgib repository (directory ${vcsPath} does not exist) (E: 2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d)`);
         }
 
         // Retrieve authoritative B2tFSIndexIbGib_V1 from space
-        const indexIbGib = await getB2tFSIndexIbGib({ space: localSpace, vcsPath });
+        const indexIbGib = await readVcsIndexProjectionFromDisk({ vcsPath, space: localSpace });
         if (!indexIbGib) {
-            throw new Error(`Repository not initialized. Run 'vcs init' first. (E: 8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3e)`);
+            throw new Error(`Repository not initialized. Run 'vcs init' first. (E: 3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d)`);
         }
 
-        const activeBranch = indexIbGib.data?.activeBranch || 'main';
+        const activeBranch = resolveContextualBranchName({ targetDir: absTargetDir, repoRoot, indexIbGib });
         const activeWorktreeDir = activeBranch === 'main' ? repoRoot : path.join(repoRoot, 'b', activeBranch);
 
-        const { space: activeSpace } = await getOrCreateBranchSpace({
+        const { space: activeBranchSpace } = await getOrCreateBranchSpace({
             metaspace,
             vcsPath,
             branchName: activeBranch,
         });
 
-        const skipPrompt = yes || force || quiet || !process.stdin.isTTY;
-        if (!skipPrompt) {
-            const msg = staged
-                ? 'Unstage specified files from index?'
-                : 'Revert working tree files to committed snapshot?';
-            const confirmed = await promptForConfirm({ msg });
-            if (!confirmed) {
-                if (!quiet) {
-                    console.log('Operation cancelled.');
-                }
-                return { unstagedPaths: [], restoredPaths: [] };
-            }
-        }
+        const { space: workspaceSpace } = await getOrCreateWorkspaceProjectionSpace({
+            metaspace,
+            workspaceRoot: activeWorktreeDir,
+            vcsFolderName,
+            backingSpace: activeBranchSpace,
+        });
 
-        let unstagedPaths: string[] | undefined;
-        let restoredPaths: string[] | undefined;
-
-        if (staged) {
-            const unstageRes = await unstagePathsFromIndex({
-                indexIbGib,
-                paths,
-                targetDir,
-                activeWorktreeDir,
-                vcsPath,
-                space: activeSpace,
-                metaspace,
-            });
-
-            if (localSpace !== activeSpace) {
-                await putInSpace({ space: localSpace, ibGib: unstageRes.updatedIndex });
-            }
+        const restoreRes = await executeVcsRestore({
+            metaspace,
+            localSpace,
+            activeBranchSpace,
+            workspaceSpace,
+            indexIbGib,
+            paths,
+            staged,
+            all,
+            targetDir: absTargetDir,
+            activeWorktreeDir,
+        });
 
-            unstagedPaths = unstageRes.unstagedPaths;
-            if (!quiet) {
-                for (const p of unstagedPaths) {
-                    console.log(`unstaged: ${p}`);
-                }
-            }
+        if (staged && restoreRes.updatedIndex) {
+            await writeVcsIndexProjectionToDisk({ vcsPath, indexIbGib: restoreRes.updatedIndex });
         }
 
-        if (!staged || worktree) {
-            const restoreRes = await restoreWorktreePathsFromSnapshot({
-                paths,
-                targetDir,
-                activeWorktreeDir,
-                activeBranchSpace: activeSpace,
-                metaspace,
-                indexIbGib,
-                vcsPath,
-            });
-
-            restoredPaths = restoreRes.restoredPaths;
-            if (!quiet) {
-                for (const p of restoredPaths) {
-                    console.log(`restored: ${p}`);
+        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 {
-            unstagedPaths,
-            restoredPaths,
+            restoredPaths: restoreRes.restoredPaths,
+            unstagedPaths: restoreRes.unstagedPaths,
         };
     } catch (error) {
         console.error(`${lc} ${extractErrorMsg(error)} (E: 9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4e)`);
         throw error;
     } finally {
         if (logalot) {
-            console.log(`${lc} complete. (I: 0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5e)`);
+            console.log(`${lc} complete. (I: 0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5f)`);
         }
     }
 }

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

@@ -8,7 +8,7 @@ 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';
@@ -16,7 +16,7 @@ import { executeStatusCmd } from './status-cmd.mjs';
 import { executeAddCmd } from './add-cmd.mjs';
 import { executeCommitCmd } from './commit-cmd.mjs';
 import { bootstrapVcsMetaspace } from '../../bootstrap/node-bootstrap.mjs';
-import { getB2tFSIndexIbGib } from '../../engine/index/index-helper.mjs';
+import { readVcsIndexProjectionFromDisk } from '../vcs-projection-helper.mjs';
 
 const lc = `[apps/vcs-gib/src/cli/commands/status-add-cmd.respec.node.mts]`;
 
@@ -142,7 +142,7 @@ await respecfully(lc, `vcs status and vcs add Command Handlers`, async () => {
                 repoPath: testDir,
                 vcsFolderName,
             });
-            const indexIbGib = await getB2tFSIndexIbGib({ space: localSpace, vcsPath });
+            const indexIbGib = await readVcsIndexProjectionFromDisk({ space: localSpace, vcsPath });
             iReckon(lc, Boolean(indexIbGib?.data?.staged_item && indexIbGib.data.staged_item.length > 0)).isGonnaBeTrue();
             iReckon(lc, indexIbGib?.rel8ns?.staged_item).isGonnaBeFalsy();