@ibgib/vcs-gib 0.0.30 → 0.0.33

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

@@ -1,363 +0,0 @@
-/**
- * @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)
- */
-
-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 { 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 { 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;
-    mergedBranchAddr?: string;
-    worktreePath: string;
-}
-
-export async function executeMergeCmd({
-    incomingBranchName,
-    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)`);
-        }
-
-        const trimmedIncomingBranch = incomingBranchName?.trim();
-        if (!trimmedIncomingBranch) {
-            throw new Error(`Branch name is required for merge (E: 5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a)`);
-        }
-
-        const absTargetDir = path.resolve(targetDir);
-
-        const { metaspace, localSpace, repoRoot, vcsPath } = 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: 6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b)`);
-        }
-
-        // 1. Fetch authoritative repository index from localSpace
-        const indexIbGib = await getB2tFSIndexIbGib({ space: localSpace, vcsPath });
-        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
-        const baseSpaceRes = await getOrCreateBranchSpace({
-            metaspace,
-            vcsPath,
-            branchName: baseBranchName,
-        });
-        const baseSpace = baseSpaceRes.space;
-
-        const incomingSpaceRes = await getOrCreateBranchSpace({
-            metaspace,
-            vcsPath,
-            branchName: trimmedIncomingBranch,
-        });
-        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
-            : path.join(repoRoot, 'b', baseBranchName);
-
-        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 });
-            }
-
-            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;
-
-                        if (childItem) {
-                            await writeB2tFSItemToFS({
-                                item: childItem,
-                                destPath: worktreePath,
-                                space: baseSpace,
-                                metaspace,
-                            });
-                        }
-                    }
-                }
-            }
-        }
-
-        if (!quiet) {
-            console.log(`Successfully merged branch '${trimmedIncomingBranch}' into '${baseBranchName}' (I: 1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a)`);
-            console.log(`  Worktree projection: ${worktreePath}`);
-        }
-
-        return {
-            baseBranch: baseBranchName,
-            incomingBranch: trimmedIncomingBranch,
-            baseSpaceId: baseSpaceRes.spaceId,
-            incomingSpaceId: incomingSpaceRes.spaceId,
-            mergedBranchAddr,
-            worktreePath,
-        };
-    } catch (error) {
-        console.error(`${lc} ${extractErrorMsg(error)} (E: 2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b)`);
-        throw error;
-    } finally {
-        if (logalot) {
-            console.log(`${lc} complete. (I: 3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c)`);
-        }
-    }
-}

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

@@ -1,128 +0,0 @@
-/**
- * @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)`);
-        }
-    }
-}

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

@@ -1,155 +0,0 @@
-/**
- * @module restore-cmd
- * 
- * Command handler for `vcs restore [path...]`.
- * Restores working tree files from committed branch snapshot, or unstages files if `--staged` is set.
- */
-
-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, restoreWorktreePathsFromSnapshot } from '../../engine/index/index-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[];
-    targetDir?: string;
-    vcsFolderName?: string;
-    staged?: boolean;
-    worktree?: boolean;
-    yes?: boolean;
-    force?: boolean;
-    quiet?: boolean;
-}
-
-export interface RestoreCmdResult {
-    unstagedPaths?: string[];
-    restoredPaths?: string[];
-}
-
-export async function executeRestoreCmd({
-    paths = [],
-    targetDir = process.cwd(),
-    vcsFolderName = '.vcsgib',
-    staged = false,
-    worktree = false,
-    yes = false,
-    force = false,
-    quiet = false,
-}: RestoreCmdOpts = {}): Promise<RestoreCmdResult> {
-    const lc = `${lcFile}[${executeRestoreCmd.name}]`;
-    try {
-        if (logalot) {
-            console.log(`${lc} starting... (I: 6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1e)`);
-        }
-
-        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: 7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2e)`);
-        }
-
-        // 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: 8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3e)`);
-        }
-
-        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 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: [] };
-            }
-        }
-
-        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 });
-            }
-
-            unstagedPaths = unstageRes.unstagedPaths;
-            if (!quiet) {
-                for (const p of unstagedPaths) {
-                    console.log(`unstaged: ${p}`);
-                }
-            }
-        }
-
-        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}`);
-                }
-            }
-        }
-
-        return {
-            unstagedPaths,
-            restoredPaths,
-        };
-    } catch (error) {
-        console.error(`${lc} ${extractErrorMsg(error)} (E: 9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4e)`);
-        throw error;
-    } finally {
-        if (logalot) {
-            console.log(`${lc} complete. (I: 0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5e)`);
-        }
-    }
-}