@ibgib/web-gib 0.0.1

package/src/api/commands/command-helpers.mts

@@ -0,0 +1,105 @@
+import { clone, extractErrorMsg, pickRandom_Letters } from "@ibgib/helper-gib/dist/helpers/utils-helper.mjs";
+
+import { GLOBAL_LOG_A_LOT } from "../../constants.mjs";
+import { APIFunctionInfo } from "../api-types.mjs";
+import { getCommandService } from "./command-service-v1.mjs";
+import { CommandDataBase } from "./command-types.mjs";
+
+const logalot = GLOBAL_LOG_A_LOT;
+
+/**
+ * customizing function to create the schema specific to some concrete schema
+ * description/instructions.
+ */
+export function tweakGeminiSchema({
+    baseSchema,
+    addlDescription,
+}: {
+    /**
+     * starting schema which we will customize.
+     */
+    baseSchema: any,
+    /**
+     * additional description, to be used for concrete schema descriptions.
+     * If there is no description to begin with, this will simply set the
+     * description.
+     *
+     * For example, with destroy renderable, describe that this will recursively
+     * destroy children. With update renderable, this will apply the changes
+     * recursively to all children (like setting color).
+     */
+    addlDescription?: string,
+}): { type: 'boolean', description: string } {
+    if (!baseSchema) { throw new Error(`(UNEXPECTED) baseSchema falsy? (E: 338a083d88ab9ae5286edc7d0c20c825)`); }
+    const resSchema = clone(baseSchema);
+    resSchema.description = `${resSchema.description ?? ''}\n${addlDescription}`;
+    return resSchema;
+}
+
+/**
+ * wraps the given {@link fn} inside of a {@link APIFunctionInfo} that can be
+ * executed on the api command service.
+ *
+ * ## intent
+ *
+ * I want to be able to execute certain functions serially similar to a barrier
+ * or critical section. This was the "easiest" way for me to do it, since each
+ * command is executed serially on the commanding service. And I didn't want to
+ * have to create APIFunctionInfo objects for things that will not be exposed to
+ * agents proper.
+ *
+ * ## NOT for agents' use
+ *
+ * because this is anon function, there is NO schema generated. So this can't be
+ * used with agents directly.
+ */
+export function commandifyAnonFn<TFunc extends (...args: any[]) => Promise<any> = (...args: any[]) => Promise<void>>({
+    fn,
+    nameOrId,
+    cmdCategory,
+}: {
+    fn: TFunc,
+    nameOrId?: string,
+    cmdCategory?: string,
+}): APIFunctionInfo<TFunc> {
+    const lc = `[${commandifyAnonFn.name}]`;
+    try {
+        if (logalot) { console.log(`${lc} starting... (I: e302e6a0f13584968379c9149406f225)`); }
+
+        const cmdName =
+            (nameOrId ?? fn.name) + `_${pickRandom_Letters({ count: 8 })}`;
+        cmdCategory ??= 'anon';
+        const cmdModifiers = [cmdName];
+
+        const fnViaCmd: any = async (opts: any) => {
+            cmdCategory ??= 'anon';
+            const commandService = getCommandService();
+            const command: CommandDataBase<typeof cmdCategory, typeof cmdModifiers> = {
+                cmd: cmdCategory,
+                cmdModifiers,
+                ...opts,
+            };
+            return new Promise<any>((resolve, reject) => {
+                commandService.enqueueCommand({ command, resolve, reject, anonApiFn });
+            });
+        }
+
+        const anonApiFn: APIFunctionInfo<TFunc> = {
+            nameOrId: cmdName,
+            cmd: cmdCategory,
+            cmdModifiers: [cmdName],
+            fnViaCmd,
+            functionImpl: fn,
+            schema: undefined,
+            isAnon: true,
+        }
+
+        return anonApiFn;
+
+    } catch (error) {
+        console.error(`${lc} ${extractErrorMsg(error)}`);
+        throw error;
+    } finally {
+        if (logalot) { console.log(`${lc} complete.`); }
+    }
+}

package/src/api/commands/command-service-v1.mts

@@ -0,0 +1,136 @@
+import { extractErrorMsg, pretty } from "@ibgib/helper-gib/dist/helpers/utils-helper.mjs";
+
+import { APIFunctionInfo } from "../api-types.mjs";
+import { CommandDataBase, CommandService, EnqueuedCommand } from "./command-types.mjs";
+import { getAllFunctionInfos } from "../api-index.mjs";
+
+/**
+ * @class CommandService_V1 - Implementation of the command service.
+ * Implements the {@link CommandService} interface.
+ */
+export class CommandService_V1 implements CommandService {
+    protected lc: string = `[${CommandService_V1.name}]`;
+    private commandQueue: EnqueuedCommand<CommandDataBase<string, string[]>>[] = [];
+    private isProcessing = false;
+
+    // private anonFns: Map<string, APIFunctionInfo<any>> = new Map();
+
+    constructor() { }
+
+    // registerAnonFn({ apiFnInfo }: { apiFnInfo: APIFunctionInfo<any> }): void {
+    //     const lc = `${this.lc}[${this.registerAnonFn.name}]`;
+    //     if (this.anonFns.has(apiFnInfo.nameOrId)) {
+    //         console.warn(`${lc} anonFn already registered? (W: c6721a63affe97f5514d54bbe780f625)`)
+    //     }
+    //     this.anonFns.set(apiFnInfo.nameOrId, apiFnInfo);
+    // }
+
+    enqueueCommand<TCommand extends CommandDataBase<string, string[]>>(enqueuedCommand: EnqueuedCommand<TCommand>): void {
+        this.commandQueue.push(enqueuedCommand);
+        if (!this.isProcessing) {
+            this.startProcessing();
+        }
+    }
+
+    private startProcessing(): void {
+        this.isProcessing = true;
+        this.processQueue().finally(() => {
+            this.isProcessing = false;
+            if (this.commandQueue.length > 0) {
+                this.startProcessing(); // If more commands were added, process them
+            }
+        });
+    }
+
+    async processQueue(): Promise<void> {
+        const lc = `${this.lc}[${this.processQueue.name}]`;
+        while (this.commandQueue.length > 0) {
+            const enqueuedCommand = this.commandQueue.shift();
+            if (enqueuedCommand) {
+                try {
+                    const result =
+                        await this.executeCommand(enqueuedCommand.command, enqueuedCommand.anonApiFn);
+                    enqueuedCommand.resolve(result);
+                } catch (error: any) {
+                    console.error(`Error executing command ${enqueuedCommand.command.cmd} ${enqueuedCommand.command.cmdModifiers?.join(',') ?? ''}:`, error);
+                    enqueuedCommand.reject(error);
+                }
+            }
+        }
+    }
+
+    private async executeCommand(cmdData: CommandDataBase<string, string[]>, anonApiFn?: APIFunctionInfo<any>): Promise<any | void> {
+        const lc = `[${CommandService_V1.name}.${this.executeCommand.name}]`;
+        try {
+            const functionInfo =
+                anonApiFn ??
+                Array.from(getAllFunctionInfos().entries())
+                    .map(x => x[1] as APIFunctionInfo<any>)
+                    .find((info) => {
+                        return info.cmd === cmdData.cmd &&
+                            info.cmdModifiers.every(modifier => !!cmdData.cmdModifiers?.includes(modifier));
+                    });
+
+            if (functionInfo) {
+                console.log(`${lc} command executing. cmdData: ${pretty(cmdData)}`)
+                // Type checking and argument passing will need refinement based on schema
+                if (cmdData.notesToSelf) {
+                    console.log(`${lc} Notes to self: ${cmdData.notesToSelf}.  (I: ebcc5471b2b309ba186281c134f77e25)`);
+                }
+                const args = this.getCommandArgs(cmdData, functionInfo);
+                const result = await functionInfo.functionImpl(args);
+                return result;
+            } else {
+                throw new Error(`${lc} Unknown command: ${cmdData.cmd} with modifiers ${cmdData.cmdModifiers?.join(', ')} (E: cc9cb829f118de05b762020213ef2825)`);
+            }
+        } catch (error) {
+            debugger; // error in command svc exec
+            const errorMsg = `${lc} ${extractErrorMsg(error)}`;
+            console.error(errorMsg);
+            return { errorMsg };
+        }
+    }
+
+    /**
+     * todo: change the structure so these explicit calls aren't necessary.
+     * @param cmdData about the cmd to invoke
+     * @param functionInfo full function info corresponding to cmd
+     * @returns args that the cmd expects depending on incoming {@link cmdData}
+     */
+    private getCommandArgs(cmdData: CommandDataBase<string, string[]>, functionInfo: APIFunctionInfo): any {
+        return cmdData as any;
+        // // This will need to be refined based on the actual function signature and schema
+        // if (functionInfo.nameOrId === 'renderableCreate') {
+        //     // return { initialStates: (cmdData as RenderableCreateCommandData).initialStates, };
+        //     return cmdData as RenderableCreateCommandData;
+        // } else if (functionInfo.nameOrId === 'renderableUpdate') {
+        //     // return { handle: (cmdData as RenderableUpdateCommandData).handle,
+        //     // updatedState: (cmdData as RenderableUpdateCommandData).updatedState
+        //     // };
+        //     return cmdData as RenderableUpdateCommandData;
+        // } else if (functionInfo.nameOrId === 'renderableDestroy') {
+        //     return cmdData as RenderableDestroyCommandData;
+        // } else if (functionInfo.nameOrId === 'tellUser') {
+        //     return { text: (cmdData as TellUserCommandData).text };
+        // } else {
+        //     throw new Error(`(UNEXPECTED) unknown command? functionInfo.nameOrId: ${functionInfo.nameOrId}, cmdData: ${pretty(cmdData)} (E: 376725f2024d48c5056a9f8989616125)`);
+        // }
+    }
+
+}
+
+/**
+ * @private
+ */
+let globalCommandService: CommandService | undefined;
+
+/**
+ * Gets the singleton instance of the CommandService.
+ * @returns {CommandService} The CommandService instance.
+ */
+export function getCommandService(): CommandService {
+    if (!globalCommandService) {
+        globalCommandService = new CommandService_V1();
+    }
+    return globalCommandService;
+}

package/src/api/commands/command-service.respec.mts

@@ -0,0 +1,72 @@
+/**
+ * @module command-service respec, not quite a real respec atow (01/2025).
+ * convert later when doing better testing. for now, just import the test function
+ * and run it to test.
+ */
+
+// import { RenderableHandle } from '../../render/render-one-file.mjs';
+// import { renderableCreateFunctionInfo } from './renderable/create-renderables.mjs';
+// import { renderableDestroyFunctionInfo } from './renderable/destroy-renderable.mts';
+// import { renderableUpdateFunctionInfo } from './renderable/update-renderable.mts';
+
+// /**
+//  * @function testCommandService - A test function to demonstrate using the command service.
+//  * @returns {Promise<void>}
+//  */
+// export async function testCommandService(): Promise<void> {
+//     console.log('>>> Starting testCommandService...');
+
+//     // 1. Create a renderable
+//     let createHandle: RenderableHandle | undefined;
+//     try {
+//         const renderableCreateViaCmd = renderableCreateFunctionInfo.fnViaCmd;
+//         // createHandle = (await renderableCreateViaCmd({
+//         const resCreate = await renderableCreateViaCmd(
+//             {
+//                 cmd: 'Renderable',
+//                 initialStates: [{
+//                     isVisible: true,
+//                     color: { r: 1, g: 0, b: 0, a: 1 }, // Red
+//                     position: { x: 10, y: 10, z: 0 },
+//                     scale: { x: 1, y: 1 },
+//                     geometry: { type: 'rect', parameters: { type: 'rect', width: 50, height: 50 } },
+//                 }],
+//             });
+
+//         createHandle = resCreate.at(0);
+//         console.log(`testCommandService: Created renderable with handle ${createHandle.uuid}`);
+//     } catch (error) {
+//         console.error('testCommandService: Error creating renderable:', error);
+//         return;
+//     }
+
+//     if (!createHandle) {
+//         console.error('testCommandService: Error creating renderable - handle is undefined. (E: 6548f5560b07137bd683cb713a4fcc24)');
+//         return;
+//     }
+
+//     // 2. Update the renderable after a short delay
+//     await new Promise(resolve => setTimeout(resolve, 2000));
+//     try {
+//         const renderableUpdateViaCmd = renderableUpdateFunctionInfo.fnViaCmd;
+//         await renderableUpdateViaCmd({
+//             handle: createHandle,
+//             updatedState: { color: { r: 0, g: 1, b: 0, a: 1 }, position: { x: 100, y: 100, z: 0 } }, // Green, moved
+//         });
+//         console.log(`testCommandService: Updated renderable with handle ${createHandle.uuid}`);
+//     } catch (error) {
+//         console.error('testCommandService: Error updating renderable:', error);
+//     }
+
+//     // 3. Destroy the renderable after another short delay
+//     await new Promise(resolve => setTimeout(resolve, 2000));
+//     try {
+//         const renderableDestroyViaCmd = renderableDestroyFunctionInfo.fnViaCmd;
+//         await renderableDestroyViaCmd({ handle: createHandle });
+//         console.log(`testCommandService: Destroyed renderable with handle ${createHandle.uuid}`);
+//     } catch (error) {
+//         console.error('testCommandService: Error destroying renderable:', error);
+//     }
+
+//     console.log('>>> Finished testCommandService.');
+// }

package/src/api/commands/command-types.mts

@@ -0,0 +1,71 @@
+import { WitnessCmdData } from "@ibgib/core-gib/dist/witness/witness-cmd/witness-cmd-types.mjs";
+import { APIFunctionInfo } from "../api-types.mjs";
+import type { getAllFunctionInfos } from "../api-index.mjs";
+
+/**
+ * @interface CommandBase - Base interface for all commands.
+ * Extends the structure for witness commands.
+ */
+export interface CommandDataBase<TCmds extends string, TCmdModifiers extends string[]> extends WitnessCmdData<TCmds, TCmdModifiers> {
+    /**
+     * notes to self for use by the LLM to describe their use of the command.
+     */
+    notesToSelf?: string;
+    /**
+     * set to true if the model desires notification as soon as the command is completed.
+     * Note that this is not part of the intrinsic command, rather it is
+     * metadata regarding agent (internal LLM model) workflow.
+     */
+    repromptWithResult?: boolean;
+}
+
+/**
+ * @interface EnqueuedCommand - Represents a command enqueued with its resolve
+ * and reject functions.
+ */
+export interface EnqueuedCommand<TCommand extends CommandDataBase<string, string[]>> {
+    command: TCommand;
+    resolve: (result: any) => void;
+    reject: (error: Error) => void;
+    /**
+     * If the command is anonymous, then this will be set. Otherwise, the APIFunctionInfo
+     * that will be used will be whitelisted from {@link getAllFunctionInfos}.
+     */
+    anonApiFn?: APIFunctionInfo<any>;
+}
+
+/**
+ * @interface CommandService - Interface for the command service.
+ */
+export interface CommandService {
+    // /**
+    //  * I'm adding this to enable anonymous functions. You must call this first
+    //  * and then you can call {@link enqueueCommand}. If you don't register, then
+    //  * you'll get an error.
+    //  *
+    //  * @see {@link commandifyAnonFn}
+    //  */
+    // registerAnonFn({ apiFnInfo }: { apiFnInfo: APIFunctionInfo<any> }): void;
+    /**
+     * Enqueues a command to be executed.
+     * @param {EnqueuedCommand<TCommand>} enqueuedCommand - The command to enqueue with its resolve and reject functions.
+     */
+    enqueueCommand<TCommand extends CommandDataBase<string, string[]>>(enqueuedCommand: EnqueuedCommand<TCommand>): void;
+
+    /**
+     * Starts processing the command queue.
+     * @returns {Promise<void>} A promise that resolves when the queue is empty.
+     */
+    processQueue(): Promise<void>;
+}
+
+// export const commandBaseSchemaProperties = {
+//     repromptWithResult: {
+//         type: 'boolean',
+//         description: `Set this to true if you want to be reprompted with the function's result.`,
+//     },
+//     notesToSelf: {
+//         type: 'string',
+//         description: `Use this as a note to yourself when looking at this function call and/or its result.`,
+//     },
+// } as const;

package/src/api/commands/ibgib/get-ibgibs.mts

@@ -0,0 +1,269 @@
+/**
+ * @module get-ibgibs.mts
+ * Provides the API Function Info for the `getIbGibs` command, which allows
+ * editing an existing ibGib using the `mut8` transform.
+ *
+ * ## notes
+ *
+ * ### ordering imports
+ *
+ * import sections always go:
+ * 1. non-ibgib deps first
+ * 2. @ibgib/helper-gib, @ibgib/encrypt-gib, @ibgib/ts-gib, @ibgib/core-gib packages (in that order)
+ * 3. import GLOBAL_LOG_A_LOT then remaining project imports
+ * 4. code proper starts with the definition of `const logalot` (if applicable)
+ *
+ * Each section is separated by a blank line.
+ */
+
+
+import { extractErrorMsg, pretty } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
+import { IbGib_V1 } from '@ibgib/ts-gib/dist/V1/types.mjs';
+import { getIbGibAddr } from '@ibgib/ts-gib/dist/helper.mjs';
+import { IbGibAddr } from '@ibgib/ts-gib/dist/types.mjs';
+import { SpaceId } from '@ibgib/core-gib/dist/witness/space/space-types.mjs';
+
+import { GLOBAL_LOG_A_LOT } from '../../../constants.mjs';
+import { APIFunctionInfo } from "../../api-types.mjs";
+import { COMMAND_BASE_SCHEMA_PROPERTIES } from "../command-constants.mjs";
+import { getCommandService } from "../command-service-v1.mjs";
+import { CommandDataBase } from "../command-types.mjs";
+import { getGlobalMetaspace_waitIfNeeded } from '../../../helpers.web.mjs';
+import { FUNCTION_CALL_EXAMPLES_HEADER } from '../../api-constants.mjs';
+import { getLatestAddrs } from '@ibgib/core-gib/dist/witness/space/space-helper.mjs';
+
+const logalot = GLOBAL_LOG_A_LOT;
+
+type IbGibMap = Record<IbGibAddr, IbGib_V1 | undefined>;
+
+// #region constants
+
+/**
+ * camelCased name of the command itself.
+ */
+const FUNCTION_NAME = 'getIbGibs';
+
+/**
+ * agent is the broad command which basically acts like a category of commands at this point.
+ */
+const CMD_CATEGORY = 'ibgib';
+/**
+ * getIbGibs here is the specific command modifier which narrows down to a command
+ * instance, similar to a fully curried function.
+ *
+ * This should be camelCased actual name of the function.
+ */
+const CMD_MODIFIERS: string[] = [FUNCTION_NAME];
+
+const EXAMPLE_INPUT_GETIBGIBS_SINGLE: Partial<GetIbGibsOpts> = {
+    ibGibAddrs: ['project SomeProject 1748386170000^A2D75E05B14E264619D24ABA4F1A1B2328E183B4524CC26029E54B84BF7BFD73.02544DDD1E042D481EAF62E36229EEC54F20C1899250D6F664ABB48A2013C994'],
+    notesToSelf: `Example of getting a single ibgib. Note that even though it's only getting a single ibgib, it still passes in an array. Usually reprompt is set because you're calling this to see the full ibgib record(s).`,
+    repromptWithResult: true,
+};
+const EXAMPLE_INPUT_GETIBGIBS_MULTIPLE: Partial<GetIbGibsOpts> = {
+    ibGibAddrs: [
+        'project SomeProject 1748386170000^A2D75E05B14E264619D24ABA4F1A1B2328E183B4524CC26029E54B84BF7BFD73.02544DDD1E042D481EAF62E36229EEC54F20C1899250D6F664ABB48A2013C994',
+        'comment HelloWorld^98289357698348694683943689487958972634583644598269186EA90A3F4A73.298986986BC82792837498759817F9827395872AC87519CDAFFE8175786E5098',
+    ],
+    notesToSelf: `Example of getting multiple ibgibs. Usually reprompt is set because you're calling this to see the full ibgib record(s).`,
+    repromptWithResult: true,
+};
+const EXAMPLES = [
+    FUNCTION_CALL_EXAMPLES_HEADER,
+    pretty(EXAMPLE_INPUT_GETIBGIBS_SINGLE),
+    pretty(EXAMPLE_INPUT_GETIBGIBS_MULTIPLE),
+].join('\n');
+const FUNCTION_DESCRIPTION = [
+    `Gets one or more full ibgib records via their addrs.`,
+    `Note that all of these must be in a single space, determined by the spaceId arg. IF not provided, then the default local user space will be used.`,
+    EXAMPLES,
+].join('\n');
+
+// #region gemini schemas
+export const GEMINI_SCHEMA_IBGIB_ADDRS = {
+    type: 'array',
+    description: 'The ibGib addresses (ib^gib) of the ibGibs to load.',
+    items: {
+        type: 'string',
+        description: 'caret-delimited ib^gib address, e.g., "comment HelloWorld^98289357698348694683943689487958972634583644598269186EA90A3F4A73.298986986BC82792837498759817F9827395872AC87519CDAFFE8175786E5098"',
+    }
+};
+const GET_IBGIBS_SCHEMA = {
+    name: FUNCTION_NAME,
+    description: FUNCTION_DESCRIPTION,
+    parameters: {
+        type: 'object',
+        properties: {
+            ...COMMAND_BASE_SCHEMA_PROPERTIES,
+            spaceId: {
+                type: 'string',
+                description: `The id of the local user space. If not provided, will use the default local space. Only provide this if you don't want to use the default space. Agents should either leave this unset, or if they are trying to mut8 an ibGib that is inside *their* subspace, then they should provide this. Otherwise, it will look in the default space which will be incorrect. In the future, agents will have a different API for interacting with their subspaces, but for now this may be used (if the agent even has access to their subspace id. it's so early in dev, I'm not sure if this is true.)`,
+            },
+            ibGibAddrs: GEMINI_SCHEMA_IBGIB_ADDRS,
+            getLatest: {
+                type: 'boolean',
+                description: 'Set to true if you want to get the latest ibgib in a timeline for the given incoming ibGibAddr. This is usually going to be true, unless you are specifically looking for ibGibs in the past or some other use case where you want the specific ibGib in time, so agents should explicitly decide this before calling this function (but no need to tell the user or anything, just make this decision).'
+            }
+        },
+        required: [
+            'ibGibAddrs',
+        ],
+    },
+};
+// #endregion gemini schemas
+
+/**
+ * @interface GetIbGibsOpts - Options for the getIbGibs command.
+ *
+ * @extends CommandDataBase
+ */
+export interface GetIbGibsOpts extends CommandDataBase<typeof CMD_CATEGORY, typeof CMD_MODIFIERS> {
+    spaceId?: SpaceId;
+    /**
+     * @property ibGibAddr - The address (or tjp address) of the project ibGib to edit.
+     */
+    ibGibAddrs: IbGibAddr[];
+    /**
+     * @property getLatest - flag that if true will get the latest version of
+     * the ibGib registered with the space.
+     */
+    getLatest?: boolean;
+}
+
+/**
+ * @interface GetIbGibsCommandData - Command data for the getIbGibs command.
+ * @extends CommandDataBase
+ */
+export interface GetIbGibsCommandData extends CommandDataBase<typeof CMD_CATEGORY, [typeof FUNCTION_NAME]> {
+    /**
+     * @see {@link GetIbGibsOpts.spaceId}
+     */
+    spaceId?: string;
+    /**
+     * @see {@link GetIbGibsOpts.ibGibAddrs}
+     */
+    ibGibAddrs: IbGibAddr[];
+    /**
+     * @see {@link GetIbGibsOpts.getLatest}
+     */
+    getLatest?: boolean;
+}
+
+export type GetIbGibsResult = IbGibMap;
+
+/**
+ * Wrapper function to enqueue the getIbGibs command.
+ * @param {GetIbGibsOpts} opts - @see {@link GetIbGibsOpts}
+ * @returns {Promise<void>} A promise that resolves when the command finishes execution.
+ */
+function getIbGibsViaCmd(opts: GetIbGibsOpts): Promise<GetIbGibsResult> {
+    const commandService = getCommandService();
+    const command: GetIbGibsCommandData = {
+        ...opts,
+        cmd: CMD_CATEGORY,
+        cmdModifiers: CMD_MODIFIERS,
+    };
+    return new Promise<GetIbGibsResult>((resolve, reject) => {
+        commandService.enqueueCommand({ command, resolve, reject });
+    });
+}
+
+/**
+ * Implementation function for the getIbGibs command.
+ *
+ * @param {GetIbGibsOpts} opts - @see {@link GetIbGibsOpts}
+ * @returns {Promise<IbGib_V1>} the new timeline ibgib
+ */
+async function getIbGibsImpl(opts: GetIbGibsOpts): Promise<GetIbGibsResult> {
+    const lc = `[${getIbGibsImpl.name}]`;
+    try {
+        if (logalot) { console.log(`${lc} starting... (I: genuuid)`); }
+
+        console.log(`${lc} ${CMD_CATEGORY} ${CMD_MODIFIERS} opts: ${pretty(opts)}`);
+
+        let { spaceId, ibGibAddrs, getLatest } = opts;
+
+        if (!ibGibAddrs) { throw new Error(`(UNEXPECTED) ibGibAddrs falsy? (E: e9beaad8ab3cf56608dd5fc79c4c1825)`); }
+        if (ibGibAddrs.length === 0) { throw new Error(`ibGibAddrs is empty (E: f0b1462f482872acba0612c8eb461925)`); }
+
+        const metaspace = await getGlobalMetaspace_waitIfNeeded();
+        if (!metaspace) { throw new Error(`${lc} metaspace falsy ($1: 85aa77c76e583edda3549ff59fadf825)`); }
+        const space = await metaspace.getLocalUserSpace({ localSpaceId: spaceId });
+        if (!space) {
+            if (!spaceId) {
+                throw new Error(`(UNEXPECTED) couldn't get default local user space? ($1: 9b1528024148052dd871b4f323881825)`);
+            } else {
+                throw new Error(`could not get local user space for spaceId (${spaceId}) ($1: genuuid)`);
+            }
+        }
+
+        let addrToLatestAddrMap: { [addr: string]: IbGibAddr } = {};
+        if (getLatest) {
+            const resLatestAddrs = await getLatestAddrs({ addrs: ibGibAddrs, space });
+            if (!resLatestAddrs.data) { throw new Error(`(UNEXPECTED) resLatestAddrs.data falsy? we tried calling getLatestAddrs and this means there is a problem lower in the lib. (E: 0baaf8072abd4feed8330ab503925b25)`); }
+            if (resLatestAddrs.data.latestAddrsMap) {
+                // addrToLatestAddrMap = resLatestAddrs.data.latestAddrsMap;
+                Object.entries(resLatestAddrs.data.latestAddrsMap)
+                    .forEach(([addr, latestAddr]) => {
+                        if (latestAddr) {
+                            addrToLatestAddrMap[addr] = latestAddr;
+                        } else {
+                            debugger; // warn - we're getting latest addrs and I don't know what it means downstream when we get a null for latest addr.
+                            console.warn(`${lc} we're getting latest addrs and I don't know what it means downstream when we get a null for latest addr. (W: bb1db99ccf189afff83a1b5807263a25)`);
+                            addrToLatestAddrMap[addr] = addr;
+                        }
+                    });
+            } else {
+                throw new Error(`(UNEXPECTED) resLatestAddrs.data.latestAddrsMap falsy? we tried calling getLatestAddrs and this was supposed to be the resulting map. This means there is a problem lower in the lib. (E: 9dcca8343a284dfb1a43cf282b82f825)`);
+            }
+        }
+
+        const addrsToGet = getLatest ?
+            Object.values(addrToLatestAddrMap) :
+            ibGibAddrs;
+
+        if (addrsToGet.length !== ibGibAddrs.length) {
+            throw new Error(`(UNEXPECTED) addrsToGet.length !== ibGibAddrs.length? at this point it's assumed that these are the same length (E: 745698a1ba78a14077d648e8d0150825)`);
+        }
+
+        let resGet = await metaspace.get({
+            addrs: addrsToGet,
+            space,
+        });
+
+        if (resGet.errorMsg || (resGet.ibGibs ?? []).length !== addrsToGet.length) {
+            throw new Error(`getIbGibs failed. error: ${extractErrorMsg(resGet.errorMsg ?? `[unknown error. resGet.ibGib length (${(resGet.ibGibs ?? []).length}). addrsToGet.length (${addrsToGet.length})]`)} (E: 09aca916068c6254580f5e29fb63e825)`);
+        }
+
+        const resMap: IbGibMap = {};
+
+        resGet.ibGibs!.forEach(ibGib => {
+            const ibGibAddr = getIbGibAddr({ ibGib });
+            const addr = addrsToGet.find(x => x === ibGibAddr);
+            if (!addr) { throw new Error(`ibGibAddr (${ibGibAddr}) in result ibGibs not found in addrsToGet (${addrsToGet})? Here are the original ibGibAddrs: ${ibGibAddrs}. Here is the resGet.ibGibs: ${pretty(resGet.ibGibs)} (E: 07535883a3a89fcb686f2409bf799825)`); }
+            resMap[ibGibAddr] = ibGib;
+        });
+
+        if (logalot) { console.log(`${lc} resMap: ${pretty(resMap)} (I: 70d79d873dd271949b48d837c286d825)`); }
+
+        return resMap;
+    } catch (error) {
+        console.error(`${lc} ${extractErrorMsg(error)}`);
+        throw error; // Re-throw the error to be caught by the command service
+    } finally {
+        // This finally block will execute regardless of whether the try block succeeds or fails.
+        if (logalot) { console.log(`${lc} complete.`); }
+    }
+}
+
+/**
+ * API function info for the getIbGibs command.
+ */
+export const getIbGibsFunctionInfo: APIFunctionInfo<typeof getIbGibsViaCmd> = {
+    nameOrId: FUNCTION_NAME,
+    fnViaCmd: getIbGibsViaCmd,
+    functionImpl: getIbGibsImpl,
+    cmd: CMD_CATEGORY,
+    cmdModifiers: CMD_MODIFIERS,
+    schema: GET_IBGIBS_SCHEMA,
+};

package/src/api/commands/ibgib/ibgib-index.mts

@@ -0,0 +1,8 @@
+import { APIFunctionInfo } from "../../api-types.mjs";
+import { getIbGibsFunctionInfo } from "./get-ibgibs.mjs";
+import { mut8IbGibFunctionInfo } from "./mut8-ibgib.mjs";
+
+export const IbGibAPIFunctionInfos: APIFunctionInfo<any>[] = [
+    getIbGibsFunctionInfo,
+    mut8IbGibFunctionInfo,
+];