@ibgib/vcs-gib 0.0.21 → 0.0.26

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

@@ -7,30 +7,16 @@
 
 import path from 'node:path';
 import fs from 'node:fs/promises';
-import { Dirent } from 'node:fs';
-import crypto from 'node:crypto';
 
 import { extractErrorMsg } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
-import { getIbGibsFromCache_fallbackToSpaces } from '@ibgib/core-gib/dist/common/other/ibgib-helper.mjs';
-
 import { bootstrapVcsMetaspace } from '../../bootstrap/node-bootstrap.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 { getIbGibWithMetaspaceFallback } from '../../engine/item/item-helper.mjs';
-import { B2tFSBranchIbGib_V1 } from '../../engine/branch/branch-types.mjs';
-import { isPathFiltered, parseFilterFileContent } from '../../engine/filter/glob-helper.mjs';
-import { getB2tFSIndexIbGib } from '../../engine/index/index-helper.mjs';
-import { B2tFSStagedItemRecord } from '../../engine/index/index-types.mjs';
 import { GLOBAL_LOG_A_LOT } from '../../vcs-gib-constants.mjs';
+import { getRepoStatus, VcsStatusItem, PendingCommentInfo } from '../../engine/status/status-helper.mjs';
 
 const lcFile = `[status-cmd]`;
 const logalot = GLOBAL_LOG_A_LOT;
 
-export interface VcsStatusItem {
-    path: string;
-    fsType: 'file' | 'folder';
-    status: 'untracked' | 'modified' | 'deleted' | 'staged';
-}
+export { VcsStatusItem, PendingCommentInfo };
 
 export interface StatusCmdResult {
     branchName: string;
@@ -38,18 +24,21 @@ export interface StatusCmdResult {
     modified: VcsStatusItem[];
     deleted: VcsStatusItem[];
     untracked: VcsStatusItem[];
+    pendingComments: PendingCommentInfo[];
 }
 
 export interface StatusCmdOpts {
     targetDir?: string;
     vcsFolderName?: string;
     quiet?: boolean;
+    comments?: boolean;
 }
 
 export async function executeStatusCmd({
     targetDir = process.cwd(),
     vcsFolderName = '.vcsgib',
     quiet = false,
+    comments = false,
 }: StatusCmdOpts = {}): Promise<StatusCmdResult> {
     const lc = `${lcFile}[${executeStatusCmd.name}]`;
 
@@ -72,170 +61,88 @@ export async function executeStatusCmd({
             throw new Error(`Not an ibgib repository (directory ${vcsPath} does not exist) (E: 4d5e6f7a8b9c10d11e12f13a14b15c6d)`);
         }
 
-        // 1. Fetch authoritative B2tFSIndexIbGib_V1 directly from localSpace
-        const indexIbGib = await getB2tFSIndexIbGib({ space: localSpace, vcsPath });
-        const branchName = indexIbGib?.data?.activeBranch || 'main';
-
-        const activeWorktreeDir = branchName === 'main' ? repoRoot : path.join(repoRoot, 'b', branchName);
-
-        // Target active branch space b2s_<activeBranch>
-        const { space: activeBranchSpace } = await getOrCreateBranchSpace({
+        const statusRes = await getRepoStatus({
             metaspace,
+            localSpace,
             vcsPath,
-            branchName,
-        });
-
-        // 2. Extract staged items directly from in-band B2tFSIndexIbGib_V1 data
-        const stagedMap = new Map<string, B2tFSStagedItemRecord>();
-        const indexStagedPaths = indexIbGib?.data?.stagedPaths || {};
-        for (const [relPath, itemRec] of Object.entries(indexStagedPaths)) {
-            stagedMap.set(relPath, itemRec);
-        }
-
-        // 3. Find active branch root item address from in-band branch graph node
-        let rootItemAddr: string | undefined;
-        const branchAddrs = [
-            ...(indexIbGib?.rel8ns?.branch || []),
-            ...(indexIbGib?.rel8ns?.branch_tjp || []),
-        ];
-
-        if (branchAddrs.length > 0) {
-            let branchIbGibs: B2tFSBranchIbGib_V1[] = [];
-            for (const bAddr of branchAddrs) {
-                const bIbGib = await getIbGibWithMetaspaceFallback({
-                    addr: bAddr,
-                    space: activeBranchSpace,
-                    metaspace,
-                });
-                if (bIbGib) {
-                    branchIbGibs.push(bIbGib as B2tFSBranchIbGib_V1);
-                }
-            }
-
-            const activeBranchIbGib = branchIbGibs.find(
-                (b) => (b as B2tFSBranchIbGib_V1)?.data?.name === branchName,
-            ) as B2tFSBranchIbGib_V1 || (branchIbGibs.at(0) as B2tFSBranchIbGib_V1);
-
-            rootItemAddr = activeBranchIbGib?.rel8ns?.b2tfs_item?.at(0);
-        }
-
-        // Read .ibgibignore patterns
-        let filterPatterns: string[] = [];
-        const ignorePath = path.join(activeWorktreeDir, '.ibgibignore');
-        try {
-            const ignoreContent = await fs.readFile(ignorePath, 'utf8');
-            filterPatterns = parseFilterFileContent(ignoreContent);
-        } catch {
-            // Ignore file missing is fine
-        }
-
-        // 4. Walk active branch graph items
-        const branchItemsMap = new Map<string, { relPath: string; fileHash?: string; fsType: 'file' | 'folder' }>();
-
-        if (rootItemAddr) {
-            const rootItem = await getIbGibWithMetaspaceFallback({
-                addr: rootItemAddr,
-                space: activeBranchSpace,
-                metaspace,
-            }) as B2tFSItemIbGib_V1;
-
-            if (rootItem) {
-                await statusCmd_walkBranchGraph({
-                    item: rootItem,
-                    space: activeBranchSpace,
-                    metaspace,
-                    currentRelPath: '',
-                    outMap: branchItemsMap,
-                });
-            }
-        }
-
-        // 5. Scan physical workspace
-        const physicalItemsMap = new Map<string, { relPath: string; fullPath: string; isDirectory: boolean; fileHash?: string }>();
-        await statusCmd_scanPhysicalWorkspace({
-            dirPath: activeWorktreeDir,
-            baseDir: activeWorktreeDir,
+            repoRoot,
             vcsFolderName,
-            filterPatterns,
-            outMap: physicalItemsMap,
         });
 
-        // 6. Categorize items into staged, modified, deleted, untracked
-        const staged: VcsStatusItem[] = [];
-        const modified: VcsStatusItem[] = [];
-        const deleted: VcsStatusItem[] = [];
-        const untracked: VcsStatusItem[] = [];
-
-        // Add staged items
-        for (const [relPath, stagedRec] of stagedMap.entries()) {
-            staged.push({
-                path: relPath,
-                fsType: stagedRec.fsType || 'file',
-                status: 'staged',
-            });
-        }
-
-        // Compare physical items against branch items and staged
-        for (const [relPath, physItem] of physicalItemsMap.entries()) {
-            if (stagedMap.has(relPath)) {
-                continue; // Staged item already reported
-            }
-
-            const branchItem = branchItemsMap.get(relPath);
-            if (!branchItem) {
-                // Not in active branch snapshot and not staged => untracked
-                untracked.push({
-                    path: relPath,
-                    fsType: physItem.isDirectory ? 'folder' : 'file',
-                    status: 'untracked',
-                });
-            } else {
-                // Tracked in branch -> check if modified
-                if (!physItem.isDirectory && physItem.fileHash && branchItem.fileHash && physItem.fileHash !== branchItem.fileHash) {
-                    modified.push({
-                        path: relPath,
-                        fsType: 'file',
-                        status: 'modified',
-                    });
-                }
-            }
-        }
+        const { branchName, staged, modified, deleted, untracked, pendingComments } = statusRes;
 
-        // Check for deleted items (in branch snapshot, but not in physical workspace and not staged)
-        for (const [relPath, branchItem] of branchItemsMap.entries()) {
-            if (!relPath || relPath === '.' || relPath === '') { continue; }
-            if (!physicalItemsMap.has(relPath) && !stagedMap.has(relPath)) {
-                deleted.push({
-                    path: relPath,
-                    fsType: branchItem.fsType,
-                    status: 'deleted',
-                });
-            }
+        const commentsByTarget = new Map<string, PendingCommentInfo[]>();
+        for (const c of pendingComments) {
+            const list = commentsByTarget.get(c.targetRelPath) || [];
+            list.push(c);
+            commentsByTarget.set(c.targetRelPath, list);
         }
 
         if (!quiet) {
             console.log(`On branch ${branchName} (I: 9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b)`);
+
             if (staged.length > 0) {
                 console.log('\nChanges to be committed:');
                 for (const item of staged) {
+                    const itemComments = commentsByTarget.get(item.path) || [];
                     console.log(`  staged:   ${item.path}`);
+                    if (itemComments.length === 0) {
+                        console.log(`    (hint: no comment file found for ${item.path} - run 'vcs gmsg')`);
+                    } else if (comments) {
+                        for (const comm of itemComments) {
+                            console.log(`    [comment: ${comm.commentRelPath}]`);
+                            const lines = comm.content.trim().split('\n');
+                            for (const line of lines) {
+                                console.log(`      ${line}`);
+                            }
+                        }
+                    }
                 }
             }
+
             if (modified.length > 0 || deleted.length > 0) {
                 console.log('\nChanges not staged for commit:');
                 for (const item of modified) {
+                    const itemComments = commentsByTarget.get(item.path) || [];
                     console.log(`  modified: ${item.path}`);
+                    if (comments && itemComments.length > 0) {
+                        for (const comm of itemComments) {
+                            console.log(`    [comment: ${comm.commentRelPath}]`);
+                            const lines = comm.content.trim().split('\n');
+                            for (const line of lines) {
+                                console.log(`      ${line}`);
+                            }
+                        }
+                    }
                 }
                 for (const item of deleted) {
                     console.log(`  deleted:  ${item.path}`);
                 }
             }
+
             if (untracked.length > 0) {
                 console.log('\nUntracked files:');
                 for (const item of untracked) {
                     console.log(`  untracked:${item.path}`);
                 }
             }
+
+            // Pending folder-level comments
+            const folderComments = pendingComments.filter(c => c.targetType === 'folder');
+            if (folderComments.length > 0) {
+                console.log('\nPending folder comments:');
+                for (const fc of folderComments) {
+                    const folderLabel = fc.targetRelPath ? fc.targetRelPath : '(root)';
+                    console.log(`  folder: ${folderLabel} [${fc.commentRelPath}]`);
+                    if (comments) {
+                        const lines = fc.content.trim().split('\n');
+                        for (const line of lines) {
+                            console.log(`      ${line}`);
+                        }
+                    }
+                }
+            }
+
             if (staged.length === 0 && modified.length === 0 && deleted.length === 0 && untracked.length === 0) {
                 console.log('nothing to commit, working tree clean');
             }
@@ -247,6 +154,7 @@ export async function executeStatusCmd({
             modified,
             deleted,
             untracked,
+            pendingComments,
         };
     } catch (error) {
         console.error(`${lc} ${extractErrorMsg(error)} (E: 5e6f7a8b9c10d11e12f13a14b15c6d7e)`);
@@ -257,110 +165,3 @@ export async function executeStatusCmd({
         }
     }
 }
-
-// #region statusCmd_walkBranchGraph
-async function statusCmd_walkBranchGraph({
-    item,
-    space,
-    metaspace,
-    currentRelPath,
-    outMap,
-}: {
-    item: B2tFSItemIbGib_V1;
-    space: any;
-    metaspace?: any;
-    currentRelPath: string;
-    outMap: Map<string, { relPath: string; fileHash?: string; fsType: 'file' | 'folder' }>;
-}): Promise<void> {
-    if (!item || !item.data) { return; }
-
-    const { fsType, fileHash } = item.data;
-    if (currentRelPath) {
-        outMap.set(currentRelPath, { relPath: currentRelPath, fileHash, fsType });
-    }
-
-    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 statusCmd_walkBranchGraph({
-                    item: childItem,
-                    space,
-                    metaspace,
-                    currentRelPath: childRelPath,
-                    outMap,
-                });
-            }
-        }
-    }
-}
-// #endregion statusCmd_walkBranchGraph
-
-// #region statusCmd_scanPhysicalWorkspace
-async function statusCmd_scanPhysicalWorkspace({
-    dirPath,
-    baseDir,
-    vcsFolderName,
-    filterPatterns,
-    outMap,
-}: {
-    dirPath: string;
-    baseDir: string;
-    vcsFolderName: string;
-    filterPatterns: string[];
-    outMap: Map<string, { relPath: string; fullPath: string; isDirectory: boolean; fileHash?: string }>;
-}): Promise<void> {
-    let entries: Dirent[] = [];
-    try {
-        entries = await fs.readdir(dirPath, { withFileTypes: true });
-    } catch {
-        return;
-    }
-
-    for (const entry of entries) {
-        const fullEntryPath = path.join(dirPath, entry.name);
-        const relPath = path.relative(baseDir, fullEntryPath).replace(/\\/g, '/');
-
-        // Ignore vcs storage folder, .git, and worktrees folder b
-        if (
-            relPath === vcsFolderName || relPath.startsWith(vcsFolderName + '/') ||
-            relPath === '.git' || relPath.startsWith('.git/') ||
-            relPath === 'b' || relPath.startsWith('b/')
-        ) {
-            continue;
-        }
-
-        if (isPathFiltered({ relativePath: relPath, isDirectory: entry.isDirectory(), filterPatterns })) {
-            continue;
-        }
-
-        if (entry.isDirectory()) {
-            outMap.set(relPath, { relPath, fullPath: fullEntryPath, isDirectory: true });
-            await statusCmd_scanPhysicalWorkspace({
-                dirPath: fullEntryPath,
-                baseDir,
-                vcsFolderName,
-                filterPatterns,
-                outMap,
-            });
-        } else if (entry.isFile()) {
-            let fileHash: string | undefined;
-            try {
-                const fileData = await fs.readFile(fullEntryPath);
-                fileHash = crypto.createHash('sha256').update(fileData).digest('hex');
-            } catch {
-                // File unreadable
-            }
-            outMap.set(relPath, { relPath, fullPath: fullEntryPath, isDirectory: false, fileHash });
-        }
-    }
-}
-// #endregion statusCmd_scanPhysicalWorkspace

package/src/cli/vcs-cli-main.mts

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 /**
  * @module vcs-cli-main
- * 
+ *
  * Executable CLI entry point for the `vcs` command line interface.
  * Parses command line arguments and dispatches execution to subcommand handlers.
  */
@@ -20,6 +20,7 @@ import { executeCheckoutCmd } from './commands/checkout-cmd.mjs';
 import { executeMergeCmd } from './commands/merge-cmd.mjs';
 import { executeResetCmd } from './commands/reset-cmd.mjs';
 import { executeRestoreCmd } from './commands/restore-cmd.mjs';
+import { executeGenerateCommentCmd } from './commands/generate-comment-cmd.mjs';
 import { AUTO_GENERATED_VERSION } from '../AUTO-GENERATED-version.mjs';
 import { GLOBAL_LOG_A_LOT } from '../vcs-gib-constants.mjs';
 
@@ -39,7 +40,8 @@ Usage:
 
 Commands:
   init [dir]            Initialize a new ibgib repository
-  status                Show repository working tree status
+  status                Show repository working tree status (-c, --comments for comment text)
+  generate-comment      Generate .ib.<file>.md metadata comment templates (synonyms: gmsg, gcomm, gen-msg, gen-comment)
   add <path...>         Stage file/folder changes (-a, --all to stage all)
   commit -m "message"   Record snapshot changes to the repository
   log                   Show commit logs
@@ -54,6 +56,7 @@ Flags:
   -v, --version         Show version information
   -m <message>          Commit message
   -b <branch>           Target branch name
+  -c, --comments        Show full comment content in status
   -a, --all             Stage all tracked/untracked files (for add/reset)
   -s, --staged          Unstage specified files from index (for restore)
   -w, --worktree        Revert physical working tree files (for restore)
@@ -91,7 +94,20 @@ export async function main({
             }
             case VCS_SUBCOMMANDS.STATUS: {
                 const targetDir = parsed.positionals[0] || process.cwd();
-                await executeStatusCmd({ targetDir });
+                await executeStatusCmd({
+                    targetDir,
+                    comments: parsed.flags.comments,
+                });
+                break;
+            }
+            case VCS_SUBCOMMANDS.GENERATE_COMMENT:
+            case VCS_SUBCOMMANDS.GEN_COMMENT:
+            case VCS_SUBCOMMANDS.GEN_MSG:
+            case VCS_SUBCOMMANDS.GCOMM:
+            case VCS_SUBCOMMANDS.GMSG: {
+                await executeGenerateCommentCmd({
+                    paths: parsed.positionals,
+                });
                 break;
             }
             case VCS_SUBCOMMANDS.ADD: {
@@ -108,8 +124,13 @@ export async function main({
                 break;
             }
             case VCS_SUBCOMMANDS.LOG: {
-                const targetDir = parsed.positionals[0] || process.cwd();
-                await executeLogCmd({ targetDir });
+                const targetDir = process.cwd();
+                const filePath = parsed.positionals[0];
+                await executeLogCmd({
+                    targetDir,
+                    filePath,
+                    allComments: parsed.flags.all,
+                });
                 break;
             }
             case VCS_SUBCOMMANDS.BRANCH: {
@@ -123,8 +144,8 @@ export async function main({
                 break;
             }
             case VCS_SUBCOMMANDS.MERGE: {
-                const targetBranchName = parsed.positionals[0] || parsed.flags.branchName;
-                await executeMergeCmd({ targetBranchName });
+                const incomingBranchName = parsed.positionals[0] || parsed.flags.branchName;
+                await executeMergeCmd({ incomingBranchName });
                 break;
             }
             case VCS_SUBCOMMANDS.RESET: {

package/src/engine/index/index-helper.mts

@@ -321,6 +321,9 @@ export async function updateB2tFSIndexIbGib({
 
         const newIndexIbGib = res.newIbGib as B2tFSIndexIbGib_V1;
         await persistTransformResult({ resTransform: res, space });
+        if (metaspace.zeroSpace && metaspace.zeroSpace !== space) {
+            await persistTransformResult({ resTransform: res, space: metaspace.zeroSpace });
+        }
         await metaspace.registerNewIbGib({ ibGib: newIndexIbGib });
 
         if (vcsPath) {

package/src/engine/item/item-helper.mts

@@ -14,11 +14,12 @@ import { Factory_V1 } from '@ibgib/ts-gib/dist/V1/factory.mjs';
 import { mut8 } from '@ibgib/ts-gib/dist/V1/transforms/mut8.mjs';
 import { rel8 } from '@ibgib/ts-gib/dist/V1/transforms/rel8.mjs';
 import { IbGib_V1 } from '@ibgib/ts-gib/dist/V1/types.mjs';
-import { TransformResult } from '@ibgib/ts-gib/dist/types.mjs';
+import { TransformResult, IbGibAddr } from '@ibgib/ts-gib/dist/types.mjs';
 import { MetaspaceService } from '@ibgib/core-gib/dist/witness/space/metaspace/metaspace-types.mjs';
 import { IbGibSpaceAny } from '@ibgib/core-gib/dist/witness/space/space-base-v1.mjs';
 import { isIbGib } from '@ibgib/core-gib/dist/common/other/ibgib-helper.mjs';
 import { persistTransformResult, getFromSpace } from '@ibgib/core-gib/dist/witness/space/space-helper.mjs';
+import { reifyDependencyGraph } from '@ibgib/core-gib/dist/common/other/graph-helper.mjs';
 
 import { GLOBAL_LOG_A_LOT } from '../../vcs-gib-constants.mjs';
 import { parseSpaceQualifiedIbGibAddr } from '../index/index-helper.mjs';
@@ -241,8 +242,11 @@ function getSpacesArray(metaAny: any): IbGibSpaceAny[] {
 async function fetchFromSpaceSilently(spaceToQuery: IbGibSpaceAny, addrToGet: string): Promise<any> {
     try {
         const resGet = await getFromSpace({ space: spaceToQuery, addrs: [addrToGet] });
-        if (resGet && resGet.success && resGet.ibGibs && resGet.ibGibs.length > 0) {
-            return resGet.ibGibs[0];
+        if (resGet) {
+            const found = resGet.ibGibs?.find(x => !!x) || (resGet.rawResultIbGib as any)?.ibGibs?.find((x: any) => !!x);
+            if (found) {
+                return found;
+            }
         }
     } catch {
         // Suppress missing address error
@@ -469,3 +473,72 @@ export async function applyB2tFSItemDiff({
         }
     }
 }
+
+// #region reifyB2tFSHierarchy
+
+export interface ReifyB2tFSHierarchyOpts {
+    /** Root B2tFS item (folder or file). Either rootItem or rootItemAddr required. */
+    rootItem?: B2tFSItemIbGib_V1;
+    /** Address of root B2tFS item. Either rootItem or rootItemAddr required. */
+    rootItemAddr?: IbGibAddr;
+    /** Space containing the branch items and updated timeline tips. */
+    space: IbGibSpaceAny;
+    /** Metaspace service instance for lookups and registrations. */
+    metaspace: MetaspaceService;
+}
+
+export interface ReifyB2tFSHierarchyResult {
+    /** The reified root B2tFS item (evolved if any descendants changed, or unchanged if no descendants changed). */
+    reifiedRootItem: B2tFSItemIbGib_V1;
+    /** True if one or more folder/file nodes in the hierarchy evolved to new tips. */
+    hasChanges: boolean;
+    /** Map of old address -> new address for every node that evolved in this reification run. */
+    reifiedAddrsMap: { [oldAddr: string]: string };
+    /** All newly evolved and persisted intermediate/root folder items created during reification. */
+    evolvedItems: B2tFSItemIbGib_V1[];
+}
+
+/**
+ * Reifies a B2tFS filesystem item hierarchy (folders and files) bottom-up.
+ *
+ * Traverses `b2tfs_child` relationship edges. If any child timeline advanced
+ * in `space` (e.g. during a 3-way merge or parallel commit), the parent folders
+ * are evolved in-place using `rel8` with the updated child tip addresses.
+ */
+export async function reifyB2tFSHierarchy({
+    rootItem,
+    rootItemAddr,
+    space,
+    metaspace,
+}: ReifyB2tFSHierarchyOpts): Promise<ReifyB2tFSHierarchyResult> {
+    const lc = `${lcFile}[${reifyB2tFSHierarchy.name}]`;
+    try {
+        if (logalot) {
+            console.log(`${lc} starting... (I: 3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a)`);
+        }
+
+        const res = await reifyDependencyGraph({
+            ibGib: rootItem,
+            ibGibAddr: rootItemAddr,
+            onlyRel8nNames: [B2TFS_CHILD_ITEM_REL8N_NAME],
+            space,
+            metaspace,
+        });
+
+        return {
+            reifiedRootItem: res.reifiedIbGib as B2tFSItemIbGib_V1,
+            hasChanges: res.hasChanges,
+            reifiedAddrsMap: res.reifiedAddrsMap,
+            evolvedItems: res.evolvedIbGibs as B2tFSItemIbGib_V1[],
+        };
+    } catch (error) {
+        console.error(`${lc} ${extractErrorMsg(error)} (E: 4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b)`);
+        throw error;
+    } finally {
+        if (logalot) {
+            console.log(`${lc} complete. (I: 5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c)`);
+        }
+    }
+}
+
+// #endregion reifyB2tFSHierarchy