@ibgib/vcs-gib 0.0.6 → 0.0.18

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

@@ -7,21 +7,215 @@
 
 import fs from 'node:fs/promises';
 import path from 'node:path';
+import crypto from 'node:crypto';
 
+import { extractErrorMsg, getUUID } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
+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 { getIbGibAddr } from '@ibgib/ts-gib/dist/helper.mjs';
+import { IbGib_V1 } from '@ibgib/ts-gib/dist/V1/types.mjs';
+import { TransformResult } 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 { getIbGibsFromCache_fallbackToSpaces } from '@ibgib/core-gib/dist/common/other/ibgib-helper.mjs';
 import { putInSpace, persistTransformResult, getFromSpace } from '@ibgib/core-gib/dist/witness/space/space-helper.mjs';
 
 import { parseSpaceQualifiedIbGibAddr } from '../index/index-helper.mjs';
+import { B2TFS_ITEM_ATOM, getB2tFSItemIb } from './item-atom-helper.mjs';
 import { GLOBAL_LOG_A_LOT } from '../../vcs-gib-constants.mjs';
 import {
-    B2tFSItemIbGib_V1, B2TFS_CHILD_ITEM_REL8N_NAME, BINARY_REL8N_NAME, B2tFSItemDiffInfo
+    B2tFSItemIbGib_V1, B2tFSItemData_V1, B2tFSItemRel8ns_V1, B2TFS_CHILD_ITEM_REL8N_NAME, BINARY_REL8N_NAME, B2tFSItemDiffInfo
 } from './item-types.mjs';
 
 const lcFile = `[item-helper]`;
 const logalot = GLOBAL_LOG_A_LOT;
 
+export interface CreateB2tFSItemIbGibOpts {
+    fsType: 'file' | 'folder';
+    name: string;
+    data?: Partial<B2tFSItemData_V1>;
+    rel8ns?: Partial<B2tFSItemRel8ns_V1>;
+}
+
+export interface EvolveB2tFSItemIbGibOpts {
+    existingItem: B2tFSItemIbGib_V1;
+    dataToUpdate?: Partial<B2tFSItemData_V1>;
+    rel8nsToUpdate?: Partial<B2tFSItemRel8ns_V1>;
+    rel8nsToRemove?: Partial<B2tFSItemRel8ns_V1>;
+}
+
+/**
+ * Creates a brand-new B2tFSItemIbGib_V1 node using Factory_V1.firstGen with TJP, DNA, and nCounter.
+ * Used ONLY for brand-new files or folders.
+ */
+export async function createB2tFSItemIbGib({
+    fsType,
+    name,
+    data,
+    rel8ns,
+}: CreateB2tFSItemIbGibOpts): Promise<TransformResult<IbGib_V1>> {
+    const lc = `${lcFile}[${createB2tFSItemIbGib.name}]`;
+    try {
+        if (logalot) {
+            console.log(`${lc} starting... (I: 8a7b6c5d4e3f2a1b0c9d8e7f6a5b4c3d)`);
+        }
+
+        if (!fsType || !name) {
+            throw new Error(`fsType and name are required (E: 9b8c7d6e5f4a3b2c1d0e9f8a7b6c5d4e)`);
+        }
+
+        const nameHash = data?.nameHash || crypto.createHash('sha256').update(name).digest('hex');
+        const uuid = data?.uuid || (await getUUID());
+        const diffTransactionId = data?.diffTransactionId || (await getUUID());
+
+        let fileNameSansExt: string | undefined;
+        let fileExt: string | undefined;
+        if (fsType === 'file') {
+            fileNameSansExt = path.parse(name).name;
+            fileExt = path.parse(name).ext.replace(/^\./, '');
+        }
+
+        const itemData: B2tFSItemData_V1 = {
+            name,
+            nameHash,
+            fsType,
+            diffTransactionId,
+            uuid,
+            classname: 'B2tFSItemIbGib_V1',
+            ...(fsType === 'file' ? { fileNameSansExt, fileExt } : {}),
+            ...data,
+        };
+
+        const ib = getB2tFSItemIb(fsType, name, nameHash);
+
+        const res = await Factory_V1.firstGen({
+            parentIbGib: Factory_V1.primitive({ ib: B2TFS_ITEM_ATOM }),
+            ib,
+            data: itemData,
+            rel8ns: rel8ns as any,
+            tjp: { timestamp: true, uuid: true },
+            dna: true,
+            nCounter: true,
+        });
+
+        if (logalot) {
+            console.log(`${lc} Created new B2tFSItemIbGib: ${res.newIbGib.ib}^${res.newIbGib.gib} (I: 0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f)`);
+        }
+
+        return res;
+    } catch (error) {
+        console.error(`${lc} ${extractErrorMsg(error)} (E: 1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a)`);
+        throw error;
+    } finally {
+        if (logalot) {
+            console.log(`${lc} complete. (I: 2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b)`);
+        }
+    }
+}
+
+/**
+ * Evolves an existing B2tFSItemIbGib_V1 node using mut8 (for data/hash updates)
+ * and rel8 (for binary/child link updates) with DNA, nCounter, and timeline tracking.
+ * Populates rel8ns.past and rel8ns.ancestor, preserving the item's TJP to generate
+ * composite two-part timeline gib addresses (<tjpGib>^<punctiliarGib>).
+ */
+export async function evolveB2tFSItemIbGib({
+    existingItem,
+    dataToUpdate,
+    rel8nsToUpdate,
+    rel8nsToRemove,
+}: EvolveB2tFSItemIbGibOpts): Promise<TransformResult<IbGib_V1>> {
+    const lc = `${lcFile}[${evolveB2tFSItemIbGib.name}]`;
+    try {
+        if (logalot) {
+            console.log(`${lc} starting... (I: 3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c)`);
+        }
+
+        if (!existingItem || !existingItem.ib || !existingItem.gib) {
+            throw new Error(`existingItem with valid ib and gib is required (E: 4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d)`);
+        }
+
+        let currentItem: B2tFSItemIbGib_V1 = existingItem;
+        const dnas: IbGib_V1[] = [];
+        const intermediateIbGibs: IbGib_V1[] = [];
+
+        // Ensure rel8ns.ancestor is populated if missing
+        if (!currentItem.rel8ns?.ancestor || currentItem.rel8ns.ancestor.length === 0) {
+            currentItem = {
+                ...currentItem,
+                rel8ns: {
+                    ...(currentItem.rel8ns || {}),
+                    ancestor: [`${B2TFS_ITEM_ATOM}^gib`],
+                },
+            };
+        }
+
+        const hasDataChanges = dataToUpdate && Object.keys(dataToUpdate).length > 0;
+        const hasRel8nsChanges = (rel8nsToUpdate && Object.keys(rel8nsToUpdate).length > 0) ||
+                                 (rel8nsToRemove && Object.keys(rel8nsToRemove).length > 0);
+
+        // If neither data nor rel8ns explicitly specified, update diffTransactionId to evolve timeline
+        const patchData: Partial<B2tFSItemData_V1> = {
+            ...(dataToUpdate || {}),
+            diffTransactionId: dataToUpdate?.diffTransactionId || (await getUUID()),
+        };
+
+        // Pass 1: mut8 for data/hash updates
+        const resMut8 = await mut8({
+            src: currentItem,
+            dataToAddOrPatch: patchData,
+            dna: true,
+            nCounter: true,
+        });
+
+        currentItem = resMut8.newIbGib as B2tFSItemIbGib_V1;
+        if (resMut8.dnas) { dnas.push(...resMut8.dnas); }
+
+        // Pass 2: rel8 for binary/child link updates if rel8ns specified
+        if (hasRel8nsChanges) {
+            intermediateIbGibs.push(currentItem);
+
+            const resRel8 = await rel8({
+                src: currentItem,
+                rel8nsToAddByAddr: rel8nsToUpdate as any,
+                rel8nsToRemoveByAddr: rel8nsToRemove as any,
+                dna: true,
+                nCounter: true,
+            });
+
+            currentItem = resRel8.newIbGib as B2tFSItemIbGib_V1;
+            if (resRel8.dnas) { dnas.push(...resRel8.dnas); }
+        }
+
+        // Verify rel8ns.ancestor exists on evolved item
+        if (!currentItem.rel8ns?.ancestor || currentItem.rel8ns.ancestor.length === 0) {
+            currentItem.rel8ns = {
+                ...(currentItem.rel8ns || {}),
+                ancestor: [`${B2TFS_ITEM_ATOM}^gib`],
+            };
+        }
+
+        if (logalot) {
+            console.log(`${lc} Evolved B2tFSItemIbGib: ${currentItem.ib}^${currentItem.gib} (I: 5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e)`);
+        }
+
+        return {
+            newIbGib: currentItem,
+            intermediateIbGibs: intermediateIbGibs.length > 0 ? intermediateIbGibs : undefined,
+            dnas: dnas.length > 0 ? dnas : undefined,
+        };
+    } catch (error) {
+        console.error(`${lc} ${extractErrorMsg(error)} (E: 6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f)`);
+        throw error;
+    } finally {
+        if (logalot) {
+            console.log(`${lc} complete. (I: 7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a)`);
+        }
+    }
+}
+
+
 function getSpacesArray(metaAny: any): IbGibSpaceAny[] {
     if (!metaAny || !metaAny.spaces) {
         return [];
@@ -141,69 +335,86 @@ export async function getIbGibWithMetaspaceFallback({
 /**
  * Projects a B2tFS item graph back onto the physical filesystem directory.
  */
-export async function writeB2tFSItemToFS(opts: {
+export async function writeB2tFSItemToFS({
+    item,
+    destPath,
+    space,
+    metaspace,
+}: {
     item: B2tFSItemIbGib_V1;
     destPath: string;
     space: IbGibSpaceAny;
     metaspace: MetaspaceService;
 }): Promise<void> {
     const lc = `${lcFile}[${writeB2tFSItemToFS.name}]`;
-    const { item, destPath, space, metaspace } = opts;
+    try {
+        if (logalot) {
+            console.log(`${lc} starting... (I: 7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d)`);
+        }
 
-    if (!item || !item.data) {
-        throw new Error(`Invalid B2tFS item provided (E: 32a09c81b29e4d58)`);
-    }
+        if (!item || !item.data) {
+            throw new Error(`Invalid B2tFS item provided (E: 32a09c81b29e4d5867198204b12541a5)`);
+        }
 
-    const { fsType, name } = item.data;
-    const targetPath = path.join(destPath, name);
+        const { fsType, name } = item.data;
+        const targetPath = path.join(destPath, name);
 
-    if (fsType === 'folder') {
-        await fs.mkdir(targetPath, { recursive: true });
-        const childAddrs = item.rel8ns?.[B2TFS_CHILD_ITEM_REL8N_NAME] || [];
+        if (fsType === 'folder') {
+            await fs.mkdir(targetPath, { recursive: true });
+            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;
+            for (const childAddr of childAddrs) {
+                const childItem = await getIbGibWithMetaspaceFallback({
+                    addr: childAddr,
+                    space,
+                    metaspace,
+                }) as B2tFSItemIbGib_V1;
 
-            if (childItem) {
-                await writeB2tFSItemToFS({
-                    item: childItem,
-                    destPath: targetPath,
+                if (childItem) {
+                    await writeB2tFSItemToFS({
+                        item: childItem,
+                        destPath: targetPath,
+                        space,
+                        metaspace,
+                    });
+                }
+            }
+        } else if (fsType === 'file') {
+            await fs.mkdir(path.dirname(targetPath), { recursive: true });
+            const binAddrs = item.rel8ns?.[BINARY_REL8N_NAME] || [];
+            const latestBinAddr = binAddrs.at(-1);
+
+            if (latestBinAddr) {
+                const binIbGib = await getIbGibWithMetaspaceFallback({
+                    addr: latestBinAddr,
                     space,
                     metaspace,
                 });
-            }
-        }
-    } else if (fsType === 'file') {
-        const binAddrs = item.rel8ns?.[BINARY_REL8N_NAME] || [];
-        const latestBinAddr = binAddrs.at(-1);
 
-        if (latestBinAddr) {
-            const binIbGib = await getIbGibWithMetaspaceFallback({
-                addr: latestBinAddr,
-                space,
-                metaspace,
-            });
+                if (binIbGib && binIbGib.data) {
+                    let fileData: Uint8Array;
+                    if (typeof binIbGib.data === 'string') {
+                        fileData = Buffer.from(binIbGib.data, 'base64');
+                    } else if (binIbGib.data instanceof Uint8Array || Buffer.isBuffer(binIbGib.data)) {
+                        fileData = binIbGib.data as Uint8Array;
+                    } else if (typeof binIbGib.data === 'object') {
+                        const vals = Object.values(binIbGib.data as object);
+                        fileData = new Uint8Array(vals);
+                    } else {
+                        fileData = new Uint8Array(0);
+                    }
 
-            if (binIbGib && binIbGib.data) {
-                let fileData: Uint8Array;
-                if (typeof binIbGib.data === 'string') {
-                    fileData = Buffer.from(binIbGib.data, 'base64');
-                } else if (binIbGib.data instanceof Uint8Array || Buffer.isBuffer(binIbGib.data)) {
-                    fileData = binIbGib.data as Uint8Array;
-                } else if (typeof binIbGib.data === 'object') {
-                    const vals = Object.values(binIbGib.data as object);
-                    fileData = new Uint8Array(vals);
-                } else {
-                    fileData = new Uint8Array(0);
+                    await fs.writeFile(targetPath, fileData);
                 }
-
-                await fs.writeFile(targetPath, fileData);
             }
         }
+    } catch (error) {
+        console.error(`${lc} ${extractErrorMsg(error)} (E: 8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d)`);
+        throw error;
+    } finally {
+        if (logalot) {
+            console.log(`${lc} complete. (I: 9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e)`);
+        }
     }
 }
 
@@ -212,28 +423,43 @@ export async function writeB2tFSItemToFS(opts: {
  * 1. Persists all child and parent transform results to space.
  * 2. Registers new IbGib pointers with metaspace to advance timeline tips.
  */
-export async function applyB2tFSItemDiff(opts: {
+export async function applyB2tFSItemDiff({
+    diff,
+    space,
+    metaspace,
+}: {
     diff: B2tFSItemDiffInfo;
     space: IbGibSpaceAny;
     metaspace: MetaspaceService;
 }): Promise<void> {
     const lc = `${lcFile}[${applyB2tFSItemDiff.name}]`;
-    const { diff, space, metaspace } = opts;
+    try {
+        if (logalot) {
+            console.log(`${lc} starting... (I: 0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d)`);
+        }
 
-    if (diff.childDiffs && diff.childDiffs.length > 0) {
-        for (const childDiff of diff.childDiffs) {
-            await applyB2tFSItemDiff({ diff: childDiff, space, metaspace });
+        if (diff.childDiffs && diff.childDiffs.length > 0) {
+            for (const childDiff of diff.childDiffs) {
+                await applyB2tFSItemDiff({ diff: childDiff, space, metaspace });
+            }
         }
-    }
 
-    const results = diff.transformResults || [];
-    for (const tr of results) {
-        await persistTransformResult({ resTransform: tr, space });
-    }
+        const results = diff.transformResults || [];
+        for (const tr of results) {
+            await persistTransformResult({ resTransform: tr, space });
+        }
 
-    for (const tr of results) {
-        if (tr.newIbGib) {
-            await metaspace.registerNewIbGib({ ibGib: tr.newIbGib });
+        for (const tr of results) {
+            if (tr.newIbGib) {
+                await metaspace.registerNewIbGib({ ibGib: tr.newIbGib });
+            }
+        }
+    } catch (error) {
+        console.error(`${lc} ${extractErrorMsg(error)} (E: 1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e)`);
+        throw error;
+    } finally {
+        if (logalot) {
+            console.log(`${lc} complete. (I: 2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f)`);
         }
     }
 }

package/src/engine/item/item.respec.mts

@@ -0,0 +1,92 @@
+/**
+ * @module item.respec.node
+ * 
+ * Unit tests for createB2tFSItemIbGib and evolveB2tFSItemIbGib timeline transforms.
+ */
+
+import {
+    respecfully, ifWe, iReckon
+} from '@ibgib/helper-gib/dist/respec-gib/respec-gib.mjs';
+import { getIbGibAddr } from '@ibgib/ts-gib/dist/helper.mjs';
+import { getGibInfo } from '@ibgib/ts-gib/dist/V1/transforms/transform-helper.mjs';
+
+import { createB2tFSItemIbGib, evolveB2tFSItemIbGib } from './item-helper.mjs';
+import { B2tFSItemIbGib_V1 } from './item-types.mjs';
+
+const lc = `[apps/vcs-gib/src/engine/item/item.respec.node.mts]`;
+
+await respecfully(lc, `B2tFS Item Timeline Transforms`, async () => {
+
+    await respecfully(lc, `createB2tFSItemIbGib`, async () => {
+        await ifWe(lc, `creates brand-new file item with TJP and DNA`, async () => {
+            const res = await createB2tFSItemIbGib({
+                fsType: 'file',
+                name: 'test.txt',
+                data: {
+                    fileHash: 'hash_abc_123',
+                },
+            });
+
+            const item = res.newIbGib as B2tFSItemIbGib_V1;
+            iReckon(lc, item).isGonnaBeTruthy();
+            iReckon(lc, item.data?.name).willEqual('test.txt');
+            iReckon(lc, item.data?.fileHash).willEqual('hash_abc_123');
+            iReckon(lc, item.rel8ns?.ancestor).isGonnaBeTruthy();
+            iReckon(lc, item.rel8ns?.tjp).isGonnaBeTruthy();
+
+            const gibInfo = getGibInfo({ gib: item.gib });
+            iReckon(lc, gibInfo.tjpGib).isGonnaBeTruthy();
+            iReckon(lc, gibInfo.punctiliarHash).isGonnaBeTruthy();
+        });
+
+        await ifWe(lc, `creates brand-new folder item`, async () => {
+            const res = await createB2tFSItemIbGib({
+                fsType: 'folder',
+                name: 'src',
+            });
+
+            const item = res.newIbGib as B2tFSItemIbGib_V1;
+            iReckon(lc, item).isGonnaBeTruthy();
+            iReckon(lc, item.data?.fsType).willEqual('folder');
+            iReckon(lc, item.data?.name).willEqual('src');
+        });
+    });
+
+    await respecfully(lc, `evolveB2tFSItemIbGib`, async () => {
+        await ifWe(lc, `evolves existing item via mut8/rel8, generating two-part timeline gib and rel8ns.past`, async () => {
+            const createRes = await createB2tFSItemIbGib({
+                fsType: 'file',
+                name: 'config.json',
+                data: {
+                    fileHash: 'hash_v1',
+                },
+            });
+
+            const initialItem = createRes.newIbGib as B2tFSItemIbGib_V1;
+            const initialAddr = getIbGibAddr({ ibGib: initialItem });
+            const initialGibInfo = getGibInfo({ gib: initialItem.gib });
+
+            // Evolve item with updated fileHash
+            const evolveRes = await evolveB2tFSItemIbGib({
+                existingItem: initialItem,
+                dataToUpdate: {
+                    fileHash: 'hash_v2',
+                },
+            });
+
+            const evolvedItem = evolveRes.newIbGib as B2tFSItemIbGib_V1;
+            const evolvedAddr = getIbGibAddr({ ibGib: evolvedItem });
+            const evolvedGibInfo = getGibInfo({ gib: evolvedItem.gib });
+
+            iReckon(lc, evolvedItem.data?.fileHash).willEqual('hash_v2');
+            iReckon(lc, evolvedItem.rel8ns?.past).includes(initialAddr);
+            iReckon(lc, evolvedItem.rel8ns?.ancestor).isGonnaBeTruthy();
+            iReckon(lc, evolvedItem.rel8ns?.tjp).willEqual(initialItem.rel8ns?.tjp);
+
+            // Verify two-part composite timeline gib address
+            iReckon(lc, evolvedGibInfo.tjpGib).willEqual(initialGibInfo.tjpGib);
+            iReckon(lc, evolvedGibInfo.punctiliarHash).isGonnaBeTruthy();
+            iReckon(lc, evolvedGibInfo.punctiliarHash !== initialGibInfo.punctiliarHash).isGonnaBeTrue();
+        });
+    });
+});