@ibgib/node-gib 0.0.22 → 0.0.23

package/dist/witness/space/node-workspace-projection-space/node-workspace-projection-space-v1.mjs

@@ -0,0 +1,326 @@
+/**
+ * @module node-workspace-projection-space-v1
+ *
+ * Concrete Node.js workspace projection space implementation.
+ * Projects B2tFS items to physical OS disk and scans physical directories.
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { clone, extractErrorMsg } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
+import { GLOBAL_LOG_A_LOT } from '@ibgib/core-gib/dist/core-constants.mjs';
+import { getFromSpace } from '@ibgib/core-gib/dist/witness/space/space-helper.mjs';
+import { WorkspaceProjectionSpaceBase_V1 } from '@ibgib/core-gib/dist/witness/space/workspace-projection-space/workspace-projection-space-base-v1.mjs';
+import { isPathFiltered, parseFilterFileContent } from '@ibgib/core-gib/dist/vcs/filter/glob-helper.mjs';
+import { DEFAULT_NODE_WORKSPACE_PROJECTION_SPACE_DATA_V1, } from './node-workspace-projection-space-types.mjs';
+const logalot = GLOBAL_LOG_A_LOT;
+/**
+ * Node.js Workspace Projection Space that projects B2tFS item DAGs directly onto
+ * the local filesystem and scans physical directories to report workspace state.
+ */
+export class NodeWorkspaceProjectionSpace_V1 extends WorkspaceProjectionSpaceBase_V1 {
+    lc = `[${NodeWorkspaceProjectionSpace_V1.name}]`;
+    /** Backing CAS space where source BinIbGibs and child items reside */
+    backingSpace;
+    constructor(initialDataOrOpts, initialRel8ns) {
+        let data;
+        let rel8ns = initialRel8ns;
+        let backingSpace;
+        if (initialDataOrOpts && ('workspaceRoot' in initialDataOrOpts || 'name' in initialDataOrOpts)) {
+            data = initialDataOrOpts;
+        }
+        else if (initialDataOrOpts && typeof initialDataOrOpts === 'object') {
+            const opts = initialDataOrOpts;
+            data = opts.initialData;
+            rel8ns = opts.initialRel8ns ?? initialRel8ns;
+            backingSpace = opts.backingSpace;
+        }
+        super(data ?? clone(DEFAULT_NODE_WORKSPACE_PROJECTION_SPACE_DATA_V1), rel8ns);
+        this.backingSpace = backingSpace;
+    }
+    // #region Implementation of Abstract Extension Hooks
+    /**
+     * Projects an item (and its recursive child hierarchy or binary payload) onto the physical workspace.
+     */
+    async putItemToWorkspaceImpl({ item, subPath, }) {
+        const lc = `${this.lc}[${this.putItemToWorkspaceImpl.name}]`;
+        try {
+            if (logalot) {
+                console.log(`${lc} projecting item to workspace...`);
+            }
+            const workspaceRoot = this.data?.workspaceRoot;
+            if (!workspaceRoot) {
+                throw new Error(`${lc} workspaceRoot is required in space data (E: 7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d)`);
+            }
+            if (!item || !item.data) {
+                throw new Error(`${lc} item and item.data are required (E: 8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e)`);
+            }
+            const { fsType, name } = item.data;
+            let itemRelPath;
+            if (subPath === undefined) {
+                itemRelPath = fsType === 'folder' ? '' : (name || '');
+            }
+            else {
+                itemRelPath = name ? (subPath ? path.join(subPath, name) : name) : subPath;
+            }
+            const targetPath = itemRelPath ? path.join(workspaceRoot, itemRelPath) : workspaceRoot;
+            if (fsType === 'folder') {
+                await fs.mkdir(targetPath, { recursive: true });
+                const childAddrs = item.rel8ns?.b2tFS_child || item.rel8ns?.b2tfs_child || [];
+                for (const childAddr of childAddrs) {
+                    const childItem = (await this.fetchIbGib(childAddr));
+                    await this.putItemToWorkspaceImpl({
+                        item: childItem,
+                        subPath: itemRelPath,
+                    });
+                }
+            }
+            else if (fsType === 'file') {
+                await fs.mkdir(path.dirname(targetPath), { recursive: true });
+                if (!item.rel8ns) {
+                    throw new Error(`${lc} item.rel8ns required for file item (E: 8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d)`);
+                }
+                const binAddrs = item.rel8ns.bin;
+                if (!binAddrs || binAddrs.length === 0) {
+                    throw new Error(`${lc} item.rel8ns.bin required for file item ${name} (E: 9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e)`);
+                }
+                const latestBinAddr = binAddrs.at(-1);
+                const binIbGib = await this.fetchIbGib(latestBinAddr);
+                if (binIbGib.data === undefined) {
+                    throw new Error(`${lc} BinIbGib at addr ${latestBinAddr} has undefined data (E: 1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a)`);
+                }
+                let fileData;
+                if (binIbGib.data instanceof Uint8Array || Buffer.isBuffer(binIbGib.data)) {
+                    fileData = binIbGib.data;
+                }
+                else if (typeof binIbGib.data === 'string') {
+                    fileData = binIbGib.data;
+                }
+                else if (typeof binIbGib.data === 'object') {
+                    const vals = Object.values(binIbGib.data);
+                    fileData = new Uint8Array(vals);
+                }
+                else {
+                    fileData = new Uint8Array(0);
+                }
+                await fs.writeFile(targetPath, fileData);
+            }
+        }
+        catch (error) {
+            console.error(`${lc} ${extractErrorMsg(error)} (E: 9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f)`);
+            throw error;
+        }
+    }
+    /**
+     * Scans the physical workspace directory and returns file observations and pending companion notes.
+     */
+    async scanWorkspaceImpl({ subPath, filterPatterns, }) {
+        const lc = `${this.lc}[${this.scanWorkspaceImpl.name}]`;
+        try {
+            if (logalot) {
+                console.log(`${lc} starting physical scan...`);
+            }
+            const workspaceRoot = this.data?.workspaceRoot;
+            if (!workspaceRoot) {
+                throw new Error(`${lc} workspaceRoot is required in space data (E: 0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a)`);
+            }
+            const scanDir = subPath ? path.join(workspaceRoot, subPath) : workspaceRoot;
+            const vcsFolderName = this.data?.vcsFolderName || '.vcsgib';
+            let patterns = filterPatterns ?? this.data?.filterPatterns;
+            if (!patterns || patterns.length === 0) {
+                try {
+                    const ignorePath = path.join(workspaceRoot, '.ibgibignore');
+                    const ignoreContent = await fs.readFile(ignorePath, 'utf8');
+                    patterns = parseFilterFileContent(ignoreContent);
+                }
+                catch {
+                    patterns = [];
+                }
+            }
+            const files = new Map();
+            const pendingComments = [];
+            await this.scanDirRecursive({
+                dirPath: scanDir,
+                baseDir: workspaceRoot,
+                vcsFolderName,
+                filterPatterns: patterns,
+                outFiles: files,
+                outComments: pendingComments,
+            });
+            return {
+                files,
+                pendingComments,
+            };
+        }
+        catch (error) {
+            console.error(`${lc} ${extractErrorMsg(error)} (E: 1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b)`);
+            throw error;
+        }
+    }
+    /**
+     * Unlinks a file, folder, or comment file from disk.
+     */
+    async deleteFromWorkspaceImpl({ relPath, ibGib, }) {
+        const lc = `${this.lc}[${this.deleteFromWorkspaceImpl.name}]`;
+        try {
+            if (logalot) {
+                console.log(`${lc} deleting from workspace...`);
+            }
+            const workspaceRoot = this.data?.workspaceRoot;
+            if (!workspaceRoot) {
+                throw new Error(`${lc} workspaceRoot is required (E: 2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c)`);
+            }
+            const targetRelPath = relPath || ibGib?.data?.name;
+            if (!targetRelPath) {
+                throw new Error(`${lc} relPath or item name required for deletion (E: 3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d)`);
+            }
+            const fullPath = path.join(workspaceRoot, targetRelPath);
+            await fs.rm(fullPath, { recursive: true, force: true });
+        }
+        catch (error) {
+            console.error(`${lc} ${extractErrorMsg(error)} (E: 4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e)`);
+            throw error;
+        }
+    }
+    /**
+     * Reads raw bytes of a physical workspace file from disk.
+     */
+    async getFileBytesImpl({ relPath, }) {
+        const lc = `${this.lc}[${this.getFileBytesImpl.name}]`;
+        try {
+            const workspaceRoot = this.data?.workspaceRoot;
+            if (!workspaceRoot) {
+                return undefined;
+            }
+            const fullPath = path.isAbsolute(relPath) ? relPath : path.join(workspaceRoot, relPath);
+            const buf = await fs.readFile(fullPath);
+            return new Uint8Array(buf);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    // #endregion
+    // #region Internal Helpers
+    /**
+     * Recursively scans physical directories on disk.
+     */
+    async scanDirRecursive({ dirPath, baseDir, vcsFolderName, filterPatterns, outFiles, outComments, }) {
+        const lc = `${this.lc}[${this.scanDirRecursive.name}]`;
+        let entries = [];
+        try {
+            entries = await fs.readdir(dirPath, { withFileTypes: true });
+        }
+        catch (error) {
+            console.error(`${lc} Failed to read directory ${dirPath}: ${extractErrorMsg(error)} (E: 5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e)`);
+            throw error;
+        }
+        for (const entry of entries) {
+            const fullEntryPath = path.join(dirPath, entry.name);
+            const relPath = path.relative(baseDir, fullEntryPath).replace(/\\/g, '/');
+            // Exclude VCS metadata folders, .git, and worktrees folder 'b'
+            if (relPath === vcsFolderName || relPath.startsWith(vcsFolderName + '/') ||
+                relPath === '.git' || relPath.startsWith('.git/') ||
+                relPath === 'b' || relPath.startsWith('b/')) {
+                continue;
+            }
+            if (this.isFiltered(relPath, entry.isDirectory(), filterPatterns)) {
+                continue;
+            }
+            if (entry.isDirectory()) {
+                outFiles.set(relPath, {
+                    relPath,
+                    fullPath: fullEntryPath,
+                    isDirectory: true,
+                });
+                await this.scanDirRecursive({
+                    dirPath: fullEntryPath,
+                    baseDir,
+                    vcsFolderName,
+                    filterPatterns,
+                    outFiles,
+                    outComments,
+                });
+            }
+            else if (entry.isFile()) {
+                if (this.isCommentMetadataFilename(entry.name)) {
+                    const parentRelPath = path.relative(baseDir, dirPath).replace(/\\/g, '/');
+                    const normalizedParent = parentRelPath === '.' ? '' : parentRelPath;
+                    let content = '';
+                    try {
+                        content = await fs.readFile(fullEntryPath, 'utf8');
+                    }
+                    catch (error) {
+                        console.error(`${lc} Failed to read comment file ${fullEntryPath}: ${extractErrorMsg(error)} (E: 6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f)`);
+                        throw error;
+                    }
+                    const topicName = this.extractCommentTopicName(entry.name);
+                    const targetRelPath = normalizedParent ? `${normalizedParent}/${topicName}` : topicName;
+                    outComments.push({
+                        commentRelPath: relPath,
+                        commentFullPath: fullEntryPath,
+                        targetRelPath,
+                        targetType: entry.name.startsWith('.ib.') ? 'file' : 'folder',
+                        topicName,
+                        content,
+                    });
+                }
+                else {
+                    let fileHash;
+                    let size;
+                    try {
+                        const fileData = await fs.readFile(fullEntryPath);
+                        fileHash = crypto.createHash('sha256').update(fileData).digest('hex');
+                        size = fileData.length;
+                    }
+                    catch (error) {
+                        console.error(`${lc} Failed to read file ${fullEntryPath}: ${extractErrorMsg(error)} (E: 7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a)`);
+                        throw error;
+                    }
+                    outFiles.set(relPath, {
+                        relPath,
+                        fullPath: fullEntryPath,
+                        isDirectory: false,
+                        fileHash,
+                        size,
+                    });
+                }
+            }
+        }
+    }
+    isCommentMetadataFilename(filename) {
+        return filename.startsWith('.ib.') && filename.endsWith('.md') && filename.length > '.ib..md'.length;
+    }
+    extractCommentTopicName(filename) {
+        if (!this.isCommentMetadataFilename(filename)) {
+            return '';
+        }
+        return filename.slice(4, -3);
+    }
+    isFiltered(relPath, isDirectory, filterPatterns) {
+        return isPathFiltered({ relativePath: relPath, isDirectory, filterPatterns });
+    }
+    /**
+     * Helper to fetch an IbGib strictly from backingSpace with fail-fast validation.
+     */
+    async fetchIbGib(addr) {
+        const lc = `${this.lc}[${this.fetchIbGib.name}]`;
+        try {
+            if (!this.backingSpace) {
+                throw new Error(`${lc} backingSpace required to fetch IbGib at ${addr} (E: 2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b)`);
+            }
+            const resGet = await getFromSpace({ space: this.backingSpace, addrs: [addr] });
+            if (!resGet.success || !resGet.ibGibs || resGet.ibGibs.length === 0) {
+                const resIbGib = resGet.rawResultIbGib;
+                const addrsNotFound = resIbGib?.data?.addrsNotFound ?? 'unknown';
+                throw new Error(`${lc} couldn't find addr ${addr} in backingSpace. addrsNotFound: ${addrsNotFound} (E: 3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c)`);
+            }
+            return resGet.ibGibs[0];
+        }
+        catch (error) {
+            console.error(`${lc} ${extractErrorMsg(error)} (E: 4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d)`);
+            throw error;
+        }
+    }
+}
+//# sourceMappingURL=node-workspace-projection-space-v1.mjs.map

package/dist/witness/space/node-workspace-projection-space/node-workspace-projection-space-v1.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-workspace-projection-space-v1.mjs","sourceRoot":"","sources":["../../../../src/witness/space/node-workspace-projection-space/node-workspace-projection-space-v1.mts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ibgib/node-gib",
-  "version": "0.0.22",
+  "version": "0.0.23",
   "description": "Node and server-specific ibGib code, i.e., things that don't run in the browser.",
   "funding": {
     "type": "individual",
@@ -26,7 +26,7 @@
   "dependencies": {
     "@ibgib/helper-gib": "^0.0.37",
     "@ibgib/ts-gib": "^0.5.34",
-    "@ibgib/core-gib": "^0.1.77",
+    "@ibgib/core-gib": "^0.1.78",
     "@ibgib/encrypt-gib": "^0.3.1"
   },
   "devDependencies": {

package/src/serve-gib/handlers/api/email/email-verify.respec.mts

@@ -33,7 +33,7 @@ await respecfully(sir, '6-Digit Verification Code & Server Quarantine Policy', a
     }
     mkdirSync(testDataDir, { recursive: true });
 
-    await ifWeMight(sir, 'generate, verify, and enforce expiration & single-use rules on magic link tokens', async () => {
+    await ifWe(sir, 'generate, verify, and enforce expiration & single-use rules on magic link tokens', async () => {
         clearConsumedNonces();
         const email = 'alice@example.com';
         const primaryTjpAddr = 'keystone^ABC123DEF456_TJP';
@@ -69,7 +69,7 @@ await respecfully(sir, '6-Digit Verification Code & Server Quarantine Policy', a
         }
     });
 
-    await ifWeMight(sir, 'create pending staging quarantine folder and AOT metadata files', async () => {
+    await ifWe(sir, 'create pending staging quarantine folder and AOT metadata files', async () => {
         clearConsumedNonces();
         const primaryTjpAddr = 'keystone^STAGING123_TJP';
         const mockKeystone = {
@@ -102,7 +102,7 @@ await respecfully(sir, '6-Digit Verification Code & Server Quarantine Policy', a
         iReckon(sir, meta1.verified).asTo('meta1 initial verified status').isGonnaBeFalse();
     });
 
-    await ifWeMight(sir, 'handle 6-digit OTP code verification and promote identity upon verification', async () => {
+    await ifWe(sir, 'handle 6-digit OTP code verification and promote identity upon verification', async () => {
         clearConsumedNonces();
         const primaryTjpAddr = 'keystone^MULTIEMAIL_TJP';
         const email = 'multi1@example.com';
@@ -162,7 +162,7 @@ await respecfully(sir, '6-Digit Verification Code & Server Quarantine Policy', a
         iReckon(sir, record?.primaryTjpAddr).asTo('record primaryTjpAddr').isGonnaBe(primaryTjpAddr);
     });
 
-    await ifWeMight(sir, 'execute atomic GC lockfile cleanup on expired staging directories', async () => {
+    await ifWe(sir, 'execute atomic GC lockfile cleanup on expired staging directories', async () => {
         clearConsumedNonces();
         const expiredTjpAddr = 'keystone^EXPIRED_TJP';
         const mockKeystone = { ib: expiredTjpAddr, data: { tjpAddr: expiredTjpAddr } };

package/src/vcs/branch-space-helper.mts

@@ -0,0 +1,109 @@
+/**
+ * @module branch-space-helper
+ * 
+ * Helper for managing dedicated Node branch spaces (`b2s_...`) in metaspace.
+ */
+
+import { clone, extractErrorMsg, getUUID } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
+import { getGib } from '@ibgib/ts-gib/dist/V1/transforms/transform-helper.mjs';
+import { Metaspace_Nodespace } from '../witness/space/metaspace/metaspace-nodespace/metaspace-nodespace.mjs';
+import { NodeFilesystemSpace_V1 } from '../witness/space/node-filesystem-space/node-filesystem-space-v1.mjs';
+import { DEFAULT_NODE_FILESYSTEM_SPACE_DATA_V1 } from '../witness/space/node-filesystem-space/node-filesystem-space-types.mjs';
+import { putInSpace } from '@ibgib/core-gib/dist/witness/space/space-helper.mjs';
+import { GLOBAL_LOG_A_LOT } from '@ibgib/core-gib/dist/core-constants.mjs';
+import { getB2tFSBranchSpaceName } from '@ibgib/core-gib/dist/vcs/branch/branch-helper.mjs';
+
+export {
+    populateBranchSpaceFromGraph,
+    PopulateBranchSpaceFromGraphOpts,
+    PopulateBranchSpaceFromGraphResult,
+} from '@ibgib/core-gib/dist/vcs/branch/branch-graph-helper.mjs';
+
+const lcFile = `[branch-space-helper]`;
+const logalot = GLOBAL_LOG_A_LOT;
+
+export interface GetOrCreateBranchSpaceOpts {
+    metaspace: Metaspace_Nodespace;
+    vcsPath: string;
+    branchName: string;
+}
+
+export interface GetOrCreateBranchSpaceResult {
+    space: NodeFilesystemSpace_V1;
+    spaceId: string;
+    spaceName: string;
+}
+
+/**
+ * Gets an existing branch space or creates and registers a new dedicated NodeFilesystemSpace_V1 in metaspace.
+ */
+export async function getOrCreateBranchSpace({
+    metaspace,
+    vcsPath,
+    branchName,
+}: GetOrCreateBranchSpaceOpts): Promise<GetOrCreateBranchSpaceResult> {
+    const lc = `${lcFile}[${getOrCreateBranchSpace.name}]`;
+    try {
+        if (logalot) {
+            console.log(`${lc} starting... (I: a1b2c3d4e5f60718293a4b5c6d7e8f9a)`);
+        }
+
+        if (!metaspace || !vcsPath || !branchName) {
+            throw new Error(`metaspace, vcsPath, and branchName are required (E: b2c3d4e5f60718293a4b5c6d7e8f9a0b)`);
+        }
+
+        const spaceName = getB2tFSBranchSpaceName(branchName);
+
+        const localSpaces = await metaspace.getLocalUserSpaces({ lock: false });
+        const existingSpace = localSpaces.find(s => s.data?.name === spaceName || s.ib === spaceName);
+
+        if (existingSpace) {
+            const spaceId = existingSpace.data?.uuid || existingSpace.data?.spaceId || spaceName;
+            if (logalot) {
+                console.log(`${lc} Found existing branch space ${spaceName} (spaceId: ${spaceId}) (I: c3d4e5f60718293a4b5c6d7e8f9a0b1c)`);
+            }
+            return {
+                space: existingSpace as NodeFilesystemSpace_V1,
+                spaceId,
+                spaceName,
+            };
+        }
+
+        const spaceUuid = await getUUID();
+        const spaceData = {
+            ...clone(DEFAULT_NODE_FILESYSTEM_SPACE_DATA_V1),
+            uuid: spaceUuid,
+            isTjp: true,
+            name: spaceName,
+            baseDir: vcsPath,
+            spaceSubPath: spaceName,
+        };
+
+        const space = new NodeFilesystemSpace_V1(spaceData);
+        space.gib = await getGib({ ibGib: space, hasTjp: true });
+        await space.initialized;
+
+        await putInSpace({ space: metaspace.zeroSpace, ibGib: space });
+        await metaspace.registerNewIbGib({ ibGib: space });
+        if (metaspace.fnUpdateBootstrap) {
+            await metaspace.fnUpdateBootstrap(space);
+        }
+
+        if (logalot) {
+            console.log(`${lc} Created new branch space ${spaceName} (spaceId: ${spaceUuid}) (I: d4e5f60718293a4b5c6d7e8f9a0b1c2d)`);
+        }
+
+        return {
+            space,
+            spaceId: spaceUuid,
+            spaceName,
+        };
+    } catch (error) {
+        console.error(`${lc} ${extractErrorMsg(error)} (E: e5f60718293a4b5c6d7e8f9a0b1c2d3e)`);
+        throw error;
+    } finally {
+        if (logalot) {
+            console.log(`${lc} complete. (I: f60718293a4b5c6d7e8f9a0b1c2d3e4f)`);
+        }
+    }
+}

package/src/vcs/workspace-space-helper.mts

@@ -0,0 +1,104 @@
+/**
+ * @module workspace-space-helper
+ *
+ * Helper for managing NodeWorkspaceProjectionSpace_V1 in metaspace.
+ */
+
+import { clone, extractErrorMsg, getUUID } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
+import { Metaspace_Nodespace } from '../witness/space/metaspace/metaspace-nodespace/metaspace-nodespace.mjs';
+import { NodeWorkspaceProjectionSpace_V1 } from '../witness/space/node-workspace-projection-space/node-workspace-projection-space-v1.mjs';
+import { IbGibSpaceAny } from '@ibgib/core-gib/dist/witness/space/space-base-v1.mjs';
+import { GLOBAL_LOG_A_LOT } from '@ibgib/core-gib/dist/core-constants.mjs';
+
+const lcFile = `[workspace-space-helper]`;
+const logalot = GLOBAL_LOG_A_LOT;
+
+export interface GetOrCreateWorkspaceProjectionSpaceOpts {
+    metaspace: Metaspace_Nodespace;
+    workspaceRoot: string;
+    vcsFolderName?: string;
+    backingSpace: IbGibSpaceAny;
+    branchAddr?: string;
+    name?: string;
+}
+
+export interface GetOrCreateWorkspaceProjectionSpaceResult {
+    space: NodeWorkspaceProjectionSpace_V1;
+    spaceId: string;
+    spaceName: string;
+}
+
+/**
+ * Gets an existing projection space for a workspace root or instantiates and returns a NodeWorkspaceProjectionSpace_V1.
+ */
+export async function getOrCreateWorkspaceProjectionSpace({
+    metaspace,
+    workspaceRoot,
+    vcsFolderName = '.vcsgib',
+    backingSpace,
+    branchAddr,
+    name,
+}: GetOrCreateWorkspaceProjectionSpaceOpts): Promise<GetOrCreateWorkspaceProjectionSpaceResult> {
+    const lc = `${lcFile}[${getOrCreateWorkspaceProjectionSpace.name}]`;
+    try {
+        if (logalot) {
+            console.log(`${lc} starting... (I: a9b8c7d6e5f4a3b2c1d0e9f8a7b6c5d4)`);
+        }
+
+        if (!metaspace || !workspaceRoot || !backingSpace) {
+            throw new Error(`metaspace, workspaceRoot, and backingSpace are required (E: a9b8c7d6e5f4a3b2c1d0e9f8a7b6c5d4)`);
+        }
+
+        const spaceName = name || `ws_${workspaceRoot.replace(/[^a-zA-Z0-9_]/g, '_')}`;
+
+        const localSpaces = (await metaspace.getLocalUserSpaces({ lock: false })) || [];
+        const existingSpace = localSpaces.find(s =>
+            (s.data?.name === spaceName || s.ib === spaceName) ||
+            (s.data?.classname?.includes('WorkspaceProjectionSpace') && s.data?.workspaceRoot === workspaceRoot)
+        );
+
+        if (existingSpace) {
+            const spaceId = existingSpace.data?.uuid || existingSpace.data?.spaceId || spaceName;
+            if (logalot) {
+                console.log(`${lc} Found existing workspace projection space ${spaceName} (spaceId: ${spaceId})`);
+            }
+            return {
+                space: existingSpace as NodeWorkspaceProjectionSpace_V1,
+                spaceId,
+                spaceName,
+            };
+        }
+
+        const spaceUuid = await getUUID();
+        const space = new NodeWorkspaceProjectionSpace_V1({
+            initialData: {
+                workspaceRoot,
+                vcsFolderName,
+                classname: 'NodeWorkspaceProjectionSpace_V1',
+                name: spaceName,
+                uuid: spaceUuid,
+                version: '1',
+                branchAddr,
+            },
+            backingSpace,
+        });
+        await space.initialized;
+
+        if (logalot) {
+            console.log(`${lc} Created new workspace projection space ${spaceName} (spaceId: ${spaceUuid})`);
+        }
+
+        return {
+            space,
+            spaceId: spaceUuid,
+            spaceName,
+        };
+    } catch (error) {
+        console.error(`${lc} ${extractErrorMsg(error)} (E: b8c7d6e5f4a3b2c1d0e9f8a7b6c5d4e3)`);
+        throw error;
+    } finally {
+        if (logalot) {
+            console.log(`${lc} complete.`);
+        }
+    }
+}

package/src/witness/space/node-workspace-projection-space/node-workspace-projection-space-constants.mts

@@ -0,0 +1,8 @@
+/**
+ * @module node-workspace-projection-space-constants
+ *
+ * Constants for Node.js workspace projection spaces.
+ */
+
+export const DEFAULT_NODE_WORKSPACE_PROJECTION_SPACE_DESCRIPTION =
+    'Node.js space witness for projecting and observing workspace hierarchies on physical disk.';

package/src/witness/space/node-workspace-projection-space/node-workspace-projection-space-types.mts

@@ -0,0 +1,43 @@
+/**
+ * @module node-workspace-projection-space-types
+ *
+ * Types for Node.js workspace projection spaces.
+ */
+
+import {
+    WorkspaceProjectionSpaceData_V1,
+    WorkspaceProjectionSpaceRel8ns_V1
+} from '@ibgib/core-gib/dist/witness/space/workspace-projection-space/workspace-projection-space-types.mjs';
+import {
+    DEFAULT_LOCAL_SPACE_POLLING_INTERVAL_MS,
+    IBGIB_SPACE_NAME_DEFAULT,
+    ZERO_SPACE_ID
+} from '@ibgib/core-gib/dist/witness/space/space-constants.mjs';
+import {
+    DEFAULT_NODE_WORKSPACE_PROJECTION_SPACE_DESCRIPTION
+} from './node-workspace-projection-space-constants.mjs';
+
+/**
+ * Data payload for NodeWorkspaceProjectionSpace_V1.
+ */
+export interface NodeWorkspaceProjectionSpaceData_V1 extends WorkspaceProjectionSpaceData_V1 {
+}
+
+export const DEFAULT_NODE_WORKSPACE_PROJECTION_SPACE_DATA_V1: NodeWorkspaceProjectionSpaceData_V1 = {
+    version: '1',
+    uuid: ZERO_SPACE_ID,
+    name: IBGIB_SPACE_NAME_DEFAULT,
+    classname: 'NodeWorkspaceProjectionSpace_V1',
+    workspaceRoot: '',
+    vcsFolderName: '.vcsgib',
+    persistOptsAndResultIbGibs: false,
+    validateIbGibAddrsMatchIbGibs: false,
+    longPollingIntervalMs: DEFAULT_LOCAL_SPACE_POLLING_INTERVAL_MS,
+    allowPrimitiveArgs: false,
+    catchAllErrors: true,
+    description: DEFAULT_NODE_WORKSPACE_PROJECTION_SPACE_DESCRIPTION,
+    trace: false,
+};
+
+export interface NodeWorkspaceProjectionSpaceRel8ns_V1 extends WorkspaceProjectionSpaceRel8ns_V1 {
+}