@ibgib/web-gib 0.0.28 → 0.0.29

package/src/app-bootstrap/helpers.web.mts

@@ -0,0 +1,243 @@
+/**
+ * @module helpers.web
+ *
+ * Shared web helper functions for ibgib-based frontend apps.
+ *
+ * ## what belongs here
+ *
+ * Functions that are identical across all ibgib apps and depend only on the
+ * IbGibAmbientContextConfig seam. App-specific logic (typed globalThis
+ * accessors, component helpers) belongs in each app's own helpers.web.mts.
+ */
+
+import { delay, extractErrorMsg } from "@ibgib/helper-gib/dist/helpers/utils-helper.mjs";
+
+import { storageGet } from "../storage/storage-helpers.web.mjs";
+import { initAppStorage } from "../helpers.web.mjs";
+import { getGlobalMetaspace_waitIfNeeded } from "../helpers.mjs";
+import { IbGibDynamicComponentMetaCtorOpts } from "../ui/component/component-types.mjs";
+import { IbGibGlobalThisInfo } from "../types.mjs";
+import { IbGibAmbientContextConfig, IbGibGlobalThis_Common, IbGibGlobalThis_IbGibApp } from "./types.mjs";
+
+// ---------------------------------------------------------------------------
+// Storage initialization
+// ---------------------------------------------------------------------------
+
+/**
+ * Initializes the IndexedDB stores required by an ibgib app.
+ *
+ * Call once on DOMContentLoaded, before the bootstrap script is dynamically
+ * loaded. This ensures storage is available when the metaspace initializes.
+ */
+export async function initIbGibStorage(config: IbGibAmbientContextConfig): Promise<void> {
+    const lc = `[${initIbGibStorage.name}]`;
+    try {
+        await initAppStorage({
+            infos: [
+                {
+                    dbName: config.dbName,
+                    storeNames: [config.storeName, ...(config.additionalStoreNames ?? [])],
+                },
+            ],
+        });
+    } catch (error) {
+        console.error(`${lc} ${extractErrorMsg(error)}`);
+        throw error;
+    }
+}
+
+// ---------------------------------------------------------------------------
+// globalThis initialization
+// ---------------------------------------------------------------------------
+
+/**
+ * Sets up globalThis.ibgib.[globalThisKey] for the given app config.
+ *
+ * Idempotent — safe to call multiple times. The root `globalThis.ibgib` object
+ * is created if it doesn't exist, then the per-app sub-key is populated.
+ *
+ * @param config  The app's ambient context config.
+ * @param globalThisKey  The snake_case key for this app's namespace under
+ *   `globalThis.ibgib` (e.g. `'my_app'`, `'cool_new_thing'`).
+ * @param version  Optional semver string (from AUTO_GENERATED_VERSION).
+ */
+export function initIbGibGlobalThis(
+    config: IbGibAmbientContextConfig,
+    globalThisKey: string,
+    version?: string,
+): void {
+    const lc = `[${initIbGibGlobalThis.name}]`;
+    try {
+        // Ensure the root ibgib object exists
+        if (!(globalThis as any).ibgib) {
+            (globalThis as any).ibgib = {
+                dbName_hack: config.dbName,
+                apiKeyName_hack: config.apiKeyName,
+                storeName_hack: config.storeName,
+            } satisfies IbGibGlobalThisInfo;
+        }
+
+        // Populate the per-app namespace
+        if (!(globalThis as any).ibgib[globalThisKey]) {
+            (globalThis as any).ibgib[globalThisKey] = {
+                version,
+                spaceShim: {},
+                fnDefaultGetAPIKey: async () => {
+                    const apiKey = await storageGet({
+                        dbName: config.dbName,
+                        storeName: config.storeName,
+                        key: config.apiKeyName,
+                    });
+                    return apiKey ?? '';
+                },
+                dbName_hack: config.dbName,
+                apiKeyName_hack: config.apiKeyName,
+                storeName_hack: config.storeName,
+            } satisfies IbGibGlobalThis_IbGibApp;
+        }
+    } catch (error) {
+        console.error(`${lc} ${extractErrorMsg(error)}`);
+        throw error;
+    }
+}
+
+// ---------------------------------------------------------------------------
+// globalThis accessors
+// ---------------------------------------------------------------------------
+
+/**
+ * Returns the raw IbGibGlobalThis_Common for the given key.
+ * Typed as the Common base — use the app-specific typed accessor for
+ * full-type access.
+ */
+export function getIbGibGlobalThis_Common(globalThisKey: string): IbGibGlobalThis_Common {
+    const lc = `[${getIbGibGlobalThis_Common.name}]`;
+    const g = (globalThis as any).ibgib?.[globalThisKey];
+    if (!g) {
+        throw new Error(`${lc} (UNEXPECTED) globalThis.ibgib.${globalThisKey} not initialized. (E: 8d621732ibgib-commonfe25)`);
+    }
+    return g as IbGibGlobalThis_Common;
+}
+
+/**
+ * Returns the IbGibGlobalThis_IbGibApp for the given key, initializing it
+ * from config if not yet present.
+ */
+export function getIbGibGlobalThis_IbGibApp(
+    globalThisKey: string,
+    config?: IbGibAmbientContextConfig,
+    version?: string,
+): IbGibGlobalThis_IbGibApp {
+    if (!(globalThis as any).ibgib?.[globalThisKey]) {
+        if (!config) {
+            throw new Error(
+                `Global context not initialized and config not provided for key '${globalThisKey}'.`
+            );
+        }
+        initIbGibGlobalThis(config, globalThisKey, version);
+    }
+    return (globalThis as any).ibgib[globalThisKey] as IbGibGlobalThis_IbGibApp;
+}
+
+// ---------------------------------------------------------------------------
+// API key helper
+// ---------------------------------------------------------------------------
+
+/**
+ * Returns a function that retrieves the AI API key from storage at call time.
+ * The globalThisKey links back to the per-app namespace for DB/store/key names.
+ */
+export function getDefaultFnGetAPIKey(
+    globalThisKey: string,
+): () => Promise<string> {
+    return async () => {
+        const gb = getIbGibGlobalThis_IbGibApp(globalThisKey);
+        return (await storageGet({
+            dbName: gb.dbName_hack,
+            storeName: gb.storeName_hack,
+            key: gb.apiKeyName_hack,
+        })) ?? '';
+    };
+}
+
+// ---------------------------------------------------------------------------
+// Dynamic bootstrap loading
+// ---------------------------------------------------------------------------
+
+/**
+ * Dynamically imports the bootstrap module at the given path and calls the
+ * named export bootstrap function.
+ *
+ * Called after DOMContentLoaded so the heavy ibgib import graph does not block
+ * first paint.
+ *
+ * @param path  Path to bootstrap.mjs (relative to the app's index.mts).
+ * @param bootstrapFnName  The exported async function to call. Defaults to
+ *   `'bootstrapApp'` — override with the app-specific function name
+ *   (e.g. `'bootstrapMyAppApp'`).
+ */
+export async function dynamicallyLoadBootstrapScript(
+    path: string,
+    bootstrapFnName: string = 'bootstrapApp',
+): Promise<void> {
+    const lc = `[${dynamicallyLoadBootstrapScript.name}]`;
+    try {
+        const module = await import(path);
+        const fn = module[bootstrapFnName];
+        if (typeof fn !== 'function') {
+            throw new Error(
+                `${lc} Bootstrap function '${bootstrapFnName}' not found in '${path}'. ` +
+                `Available exports: ${Object.keys(module).join(', ')} (E: 9136085eibgib-common26)`
+            );
+        }
+        await fn();
+    } catch (error) {
+        console.error(`${lc} ${extractErrorMsg(error)}`);
+        throw error;
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Component constructor args helper
+// ---------------------------------------------------------------------------
+
+/**
+ * Returns the standard ctor options object for IbGib dynamic components.
+ *
+ * Provides two things components need at construction time:
+ * 1. `fnGetMetaspace` — accesses the global metaspace once initialized
+ * 2. `bootstrapPromise` — components can await this to defer their own init
+ *    until the App witness and metaspace are fully ready
+ *
+ * @param globalThisKey  The per-app namespace key used to find the bootstrap
+ *   promise on globalThis.
+ */
+export function getComponentCtorArg(globalThisKey: string): IbGibDynamicComponentMetaCtorOpts {
+    const fnGetMetaspace = async () => getGlobalMetaspace_waitIfNeeded();
+
+    const bootstrapPromiseWrapper = new Promise<void>(async (resolve, reject) => {
+        try {
+            let maxTries = 100_000;
+            let counter = 0;
+            let bootstrapPromise: Promise<void> | undefined;
+            do {
+                bootstrapPromise =
+                    getIbGibGlobalThis_IbGibApp(globalThisKey)?.bootstrapPromise;
+                counter++;
+                if (counter > maxTries) { break; }
+                await delay(10);
+            } while (bootstrapPromise === undefined);
+            if (!bootstrapPromise) {
+                throw new Error(
+                    `Timed out waiting for bootstrapPromise on key '${globalThisKey}'. (E: 4048ce92ibgib-common26)`
+                );
+            }
+            await bootstrapPromise;
+            resolve();
+        } catch (error) {
+            reject(error);
+        }
+    });
+
+    return { fnGetMetaspace, bootstrapPromise: bootstrapPromiseWrapper };
+}

package/src/app-bootstrap/types.mts

@@ -0,0 +1,190 @@
+/**
+ * @module types
+ *
+ * Shared type definitions for ibgib-based frontend apps.
+ *
+ * ## notes
+ *
+ * Three layers of globalThis state:
+ *   IbGibGlobalThisInfo          (@ibgib/web-gib — the root ibgib slot)
+ *       └── IbGibGlobalThis_Common     (bootstrap promise tracking)
+ *               └── IbGibGlobalThis_IbGibApp  (all ibgib App witness apps)
+ *                       └── IbGibGlobalThis_[AppName]   (per-app extensions)
+ */
+
+import { IbGibRel8ns_V1, IbGib_V1 } from "@ibgib/ts-gib/dist/V1/types.mjs";
+import { CommentData_V1 } from "@ibgib/core-gib/dist/common/comment/comment-types.mjs";
+import { RCLIArgInfo } from "@ibgib/helper-gib/dist/rcli/rcli-types.mjs";
+
+import { LiveProxyIbGib } from "../witness/live-proxy-ibgib/live-proxy-ibgib-one-file.mjs";
+import { IbGibGlobalThisInfo } from "../types.mjs";
+
+// ---------------------------------------------------------------------------
+// App ambient context config
+// ---------------------------------------------------------------------------
+
+/**
+ * Configuration object that parameterizes an ibgib app's storage substrates.
+ *
+ * This is the primary seam between the framework layer and a specific app.
+ * Every downstream app creates exactly one APP_CONFIG and passes it to the
+ * framework helpers.
+ *
+ * ## notes
+ *
+ * Intended to be upstreamed into @ibgib/web-gib.
+ */
+export interface IbGibAmbientContextConfig {
+    /** Target IndexedDB database name */
+    dbName: string;
+    /** Primary object store name */
+    storeName: string;
+    /** Additional stores to initialize alongside the primary (e.g., ZERO_SPACE_ID) */
+    additionalStoreNames?: string[];
+    /** The IndexedDB key under which the AI API key is persisted */
+    apiKeyName: string;
+}
+
+// ---------------------------------------------------------------------------
+// Space shim (RCLI pathing compat layer)
+// ---------------------------------------------------------------------------
+
+/**
+ * Per-space shim that mimics a filesystem CWD context for ibgib RCLI compat.
+ */
+export interface SpaceShimGlobalInfo {
+    /**
+     * The initial cwd() value when the RCLI was started. Used as the context
+     * path the user types commands from.
+     */
+    initialCwd: string;
+    /** The active CWD, updated by pass-through `cd` commands. */
+    cwd: string;
+}
+
+// ---------------------------------------------------------------------------
+// Bootstrap request comment (RCLI plumbing)
+// ---------------------------------------------------------------------------
+
+/** @see {@link RequestCommentIbGib_V1} */
+export interface RequestCommentData_V1 extends CommentData_V1 {
+    /** As close to the raw args as we can get. */
+    args: string[];
+    /** Interpreted infos for args. */
+    interpretedArgInfos: RCLIArgInfo[];
+}
+
+export interface RequestCommentRel8ns_V1 extends IbGibRel8ns_V1 { }
+
+/**
+ * Special Comment ibgib that acts as a "request" — the command analog from RCLI.
+ *
+ * The raw text of the command is `text` from `CommentData_V1`.
+ */
+export interface RequestCommentIbGib_V1
+    extends IbGib_V1<RequestCommentData_V1, RequestCommentRel8ns_V1> {
+    /** Kluge for one-off commandlines during initial development. */
+    oneOff: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Identity (optional — WIP as of April 2026)
+// ---------------------------------------------------------------------------
+
+/**
+ * Framework-level identity interface.
+ *
+ * ## design notes
+ *
+ * The implementation is entirely consumer-supplied. The framework defines only
+ * the shape of the slot so shells and components can react to auth state
+ * without coupling to a specific identity mechanism.
+ *
+ * For ibgib apps, the typical implementation will be keystone-based (a Merkle
+ * DAG proof of cryptographic identity continuity), not token-based.
+ *
+ * ## WIP caveat (atow April 2026)
+ *
+ * The keystone identity implementation in @ibgib/core-gib is still under
+ * active development. This interface represents the intended framework
+ * contract. Check the ibgib-libs sync/keystone module for the current
+ * implementation status before using.
+ */
+export interface IbGibIdentityContext {
+    /** Whether identity resolution has completed (does not imply authenticated). */
+    resolved: boolean;
+    /** Whether the current session has a verified identity. */
+    authenticated: boolean;
+    /**
+     * App-specific identity payload.
+     * For ibgib: typically `{ keystoneAddr, userIbGibAddr }`.
+     */
+    data?: Record<string, any>;
+}
+
+// ---------------------------------------------------------------------------
+// GlobalThis layers
+// ---------------------------------------------------------------------------
+
+/**
+ * Layer 1: Fields shared across ALL ibgib web apps.
+ *
+ * Extends IbGibGlobalThisInfo from @ibgib/web-gib (the root ibgib slot).
+ * Intended to be upstreamed into @ibgib/web-gib.
+ */
+export interface IbGibGlobalThis_Common extends IbGibGlobalThisInfo {
+    /**
+     * Set to true when bootstrap has been triggered.
+     * There is no "bootstrapComplete" — await {@link bootstrapPromise} instead.
+     */
+    bootstrapStarted?: boolean;
+    /**
+     * The promise returned by the bootstrap function. Components await this
+     * to defer initialization until the App witness and metaspace are ready.
+     */
+    bootstrapPromise?: Promise<void>;
+    /**
+     * Singleton chronologys component. Should not be destroyed for the
+     * duration of the page session.
+     */
+    chronologysComponent?: any;
+}
+
+/**
+ * Layer 2: Fields shared by any app that follows the ibgib App witness pattern.
+ *
+ * Apps using the bootstrap factory pattern extend this interface and add only
+ * their app-specific fields.
+ *
+ * ## notes
+ *
+ * Intended to be upstreamed into @ibgib/web-gib as IbGibGlobalThis_IbGibApp.
+ */
+export interface IbGibGlobalThis_IbGibApp extends IbGibGlobalThis_Common {
+    /** Semver string generated at build time. */
+    version?: string;
+    /** Per-space RCLI pathing shim. */
+    spaceShim: { [spaceId: string]: SpaceShimGlobalInfo };
+    /** When true, verbose output is enabled for the session. */
+    verbose?: boolean;
+    /**
+     * Looks up the AI API key from IndexedDB storage.
+     * Stored as a function so the key is never cached in memory at the global level.
+     */
+    fnDefaultGetAPIKey: () => Promise<string>;
+    /** The initial "command" comment ibgib created at bootstrap time. */
+    initialCommentIbGib?: IbGib_V1;
+    /** Live proxy wrapping {@link initialCommentIbGib} for reactive subscriptions. */
+    initialCommentIbGibProxy?: LiveProxyIbGib;
+    /**
+     * Optional identity context. Populated by the consumer's resolveIdentity()
+     * callback in the bootstrap options.
+     *
+     * - `undefined`: no identity mechanism configured
+     * - `null`: identity resolution was attempted; user is unauthenticated
+     * - `IbGibIdentityContext`: identity resolved (check `.authenticated`)
+     *
+     * @see {@link IbGibIdentityContext}
+     */
+    identity?: IbGibIdentityContext | null;
+}

package/tools/auto-generated-agent-skills/skills/ibgib-create-app-core/SKILL.md

@@ -36,13 +36,13 @@ This skill is often the first step in creating a new app, or used to "ibgib-ify"
 
 | Token | Example value | How it's computed |
 |---|---|---|
-| `{{APP_HUMAN_NAME}}` | `PulmonIQ Learning` | Asked of developer |
-| `{{APP_NAME_UPPER}}` | `PULMONIQ_LEARNING` | Uppercase + underscores of app name |
-| `{{APP_CLASSNAME_PREFIX}}` | `PulmoniqLearning` | PascalCase, no suffix |
-| `{{APP_DIR_NAME}}` | `pulmoniq-learning` | kebab-case |
-| `{{DB_NAME}}` | `pulmoniq_learning_db` | Asked of developer |
-| `{{STORE_NAME}}` | `pulmoniq_learning_store` | Asked of developer |
-| `{{APP_UUID}}` | `8d6217327e6490650169be9cb22a0b25` | **Generated fresh** with `generate-id.js`. |
+| `{{APP_HUMAN_NAME}}` | `My App` | Asked of developer |
+| `{{APP_NAME_UPPER}}` | `MY_APP` | Uppercase + underscores of app name |
+| `{{APP_CLASSNAME_PREFIX}}` | `MyApp` | PascalCase, no suffix |
+| `{{APP_DIR_NAME}}` | `my-app` | kebab-case |
+| `{{DB_NAME}}` | `my_app_db` | Asked of developer |
+| `{{STORE_NAME}}` | `my_app_store` | Asked of developer |
+| `{{APP_UUID}}` | `3a95fe65cbda2833b59cadff4e279826` | **Generated fresh** with `generate-id.js`. |
 
 ---
 

package/tools/auto-generated-agent-skills/skills/ibgib-create-app-core/templates/types.mts.template

@@ -7,9 +7,6 @@ import { IbGibGlobalThisInfo } from "@ibgib/web-gib/dist/types.mjs";
 
 // ---------------------------------------------------------------------------
 // App-level ambient context config
-//
-// NOTE: This interface is intentionally agnostic to pulmoniq or any other
-// domain. It should eventually be upstreamed into @ibgib/web-gib.
 // ---------------------------------------------------------------------------
 
 /**