@ibgib/web-gib 0.0.23 → 0.0.25

package/tools/auto-generated-agent-skills/skills/ibgib-add-core-engine/templates/types.mts.template

@@ -0,0 +1,128 @@
+import { CommentData_V1 } from "@ibgib/core-gib/dist/common/comment/comment-types.mjs";
+import { MetaspaceService } from "@ibgib/core-gib/dist/witness/space/metaspace/metaspace-types.mjs";
+import { RCLIArgInfo } from "@ibgib/helper-gib/dist/rcli/rcli-types.mjs";
+import { IbGibRel8ns_V1, IbGib_V1 } from "@ibgib/ts-gib/dist/V1/types.mjs";
+import { LiveProxyIbGib } from "@ibgib/web-gib/dist/witness/live-proxy-ibgib/live-proxy-ibgib-one-file.mjs";
+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.
+// ---------------------------------------------------------------------------
+
+/**
+ * Configuration for the application's global state and storage substrates.
+ */
+export interface IbGibAmbientContextConfig {
+    /** Target IndexedDB database name */
+    dbName: string;
+    /** Primary object store name */
+    storeName: string;
+    /** Additional stores that need to be initialized (e.g., zero space ID) */
+    additionalStoreNames?: string[];
+    /** The IndexedDB key under which the AI API key is persisted */
+    apiKeyName: string;
+}
+
+// ---------------------------------------------------------------------------
+// Bootstrap request comment (RCLI plumbing)
+// ---------------------------------------------------------------------------
+
+export interface RequestCommentData_V1 extends CommentData_V1 {
+    args: string[];
+    interpretedArgInfos: RCLIArgInfo[];
+}
+
+export interface RequestCommentRel8ns_V1 extends IbGibRel8ns_V1 {}
+
+/**
+ * Special Comment that acts as a "request" — the command analog from RCLI.
+ */
+export interface RequestCommentIbGib_V1
+    extends IbGib_V1<RequestCommentData_V1, RequestCommentRel8ns_V1> {
+    oneOff: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Space shim (RCLI pathing compat)
+// ---------------------------------------------------------------------------
+
+export interface SpaceShimGlobalInfo {
+    initialCwd: string;
+    cwd: string;
+}
+
+// ---------------------------------------------------------------------------
+// Identity (optional — only populate if the app uses identity)
+// ---------------------------------------------------------------------------
+
+/**
+ * Framework-level identity interface.
+ *
+ * ## notes
+ *
+ * The implementation is entirely consumer-supplied. The framework only defines
+ * the shape of the slot so that shells and components can react to auth state
+ * without being coupled to a specific identity mechanism.
+ *
+ * For ibgib apps, the typical implementation will be keystone-based (a
+ * Merkle DAG proof of identity), not token-based.
+ */
+export interface IbGibIdentityContext {
+    /** Whether identity resolution has completed (does not imply authenticated). */
+    resolved: boolean;
+    /** Whether the user has a verified identity in this session. */
+    authenticated: boolean;
+    /**
+     * App-specific identity payload.
+     * For ibgib: typically includes keystoneAddr, userIbGibAddr, etc.
+     */
+    data?: Record<string, any>;
+}
+
+// ---------------------------------------------------------------------------
+// GlobalThis state
+// ---------------------------------------------------------------------------
+
+/**
+ * Base layer: fields shared across ALL ibgib web apps.
+ *
+ * NOTE: This is a superset of IbGibGlobalThisInfo from @ibgib/web-gib.
+ * Intended to be upstreamed eventually.
+ */
+export interface IbGibGlobalThis_Common extends IbGibGlobalThisInfo {
+    bootstrapStarted?: boolean;
+    bootstrapPromise?: Promise<void>;
+    chronologysComponent?: any;
+}
+
+/**
+ * Mid-layer: fields shared by any app that uses the ibgib App witness pattern.
+ *
+ * NOTE: Intended to be upstreamed into @ibgib/web-gib as IbGibGlobalThis_IbGibApp.
+ */
+export interface IbGibGlobalThis_IbGibApp extends IbGibGlobalThis_Common {
+    version?: string;
+    spaceShim: { [spaceId: string]: SpaceShimGlobalInfo };
+    verbose?: boolean;
+    fnDefaultGetAPIKey: () => Promise<string>;
+    initialCommentIbGib?: IbGib_V1;
+    initialCommentIbGibProxy?: LiveProxyIbGib;
+    /**
+     * Optional. Populated by the consumer's resolveIdentity() callback.
+     * Undefined = identity not configured. Null = unresolved/unauthenticated.
+     */
+    identity?: IbGibIdentityContext | null;
+}
+
+// ---------------------------------------------------------------------------
+// App-specific globalThis — add only what this app uniquely needs below
+// ---------------------------------------------------------------------------
+
+export interface IbGibGlobalThis_{{APP_CLASSNAME_PREFIX}} extends IbGibGlobalThis_IbGibApp {
+    {{APP_VAR_NAME}}ShellSvc?: any;
+    // TODO: add app-specific singleton references here, e.g.:
+    // currentModuleAddr?: string;
+}

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

@@ -0,0 +1,59 @@
+---
+name: ibgib-create-app-witness
+description: >
+  Scaffolds the App Witness (engine) logic for an ibgib application.
+  Generates the core business logic files including the App class,
+  constants, helpers, and types.
+---
+
+# Skill: ibgib-create-app-witness
+
+## What This Skill Does
+
+Generates the "Brain" of an ibgib app. In ibgib architecture, the App Witness is a class that reacts to "Request Comments" (commands) sent by the user or-other agents.
+
+This skill scaffolds:
+- **App Class**: Inherits from `AppBase_V1` and handles the initial `--interactive` request to boot the app.
+- **App Constants**: Defines `PARAM_INFOS` and the app's internal command set.
+- **App Helpers**: boilerplate for creating request comments and validating parameters.
+- **App Types**: Data and Relationship structures unique to this app.
+- **API Registration**: Plumbing to register core app functions with the ibgib runtime.
+
+---
+
+## Token Reference
+
+| Token | Example value | How it's computed |
+|---|---|---|
+| `{{APP_DIR_NAME}}` | `test-app` | kebab-case name of the app |
+| `{{APP_CLASSNAME_PREFIX}}` | `TestApp` | PascalCase, no suffix |
+| `{{APP_CLASSNAME}}` | `TestAppApp_V1` | PascalCase + `App_V1` |
+| `{{APP_NAME_UPPER}}` | `TEST_APP` | Uppercase + underscores |
+| `{{APP_UUID}}` | `8d6217327e6490650169be9cb22a0b25` | Use the SAME UUID as in the core-engine. |
+
+---
+
+## Generation Steps
+
+### 1. Confirm Tokens
+Ensure you have the same tokens used in `ibgib-add-core-engine`.
+
+### 2. Generate Files
+Apply substitutions to templates and write to the target directory (usually `src/`).
+
+| Template file | Output file |
+|---|---|
+| `templates/witness/app/app-v1.mts.template` | `witness/app/{{APP_DIR_NAME}}/{{APP_DIR_NAME}}-app-v1.mts` |
+| `templates/witness/app/constants.mts.template` | `witness/app/{{APP_DIR_NAME}}/{{APP_DIR_NAME}}-constants.mts` |
+| `templates/witness/app/helper.mts.template` | `witness/app/{{APP_DIR_NAME}}/{{APP_DIR_NAME}}-helper.mts` |
+| `templates/witness/app/types.mts.template` | `witness/app/{{APP_DIR_NAME}}/{{APP_DIR_NAME}}-types.mts` |
+| `templates/api/function-infos.web.mts.template` | `api/function-infos.web.mts` |
+
+### 3. Replace `genuuid` placeholders
+Replace all `genuuid` strings in the templates with fresh IDs from `generate-id.js`.
+
+---
+
+## Reference Implementations
+- `apps/learning/src/witness/app/pulmoniq-learning/` — Historical reference for full-featured witnesses.
+- `apps/website/src/witness/app/pulmoniq-website/` — Historical reference for shell-service witnesses.

package/tools/auto-generated-agent-skills/skills/ibgib-create-app-witness/templates/api/function-infos.web.mts.template

@@ -0,0 +1,11 @@
+/**
+ * @module function-infos.web
+ * 
+ * Logic to register app-specific functions with the ibgib runtime.
+ * Useful for exposing functionality to the Agent/AI layer.
+ */
+
+export function registerDeprecatedFunctionNamesAndFunctionInfos_Web(): void {
+    // Boilerplate for future API registrations.
+    // console.log("Registering app functions... (I: genuuid)");
+}

package/tools/auto-generated-agent-skills/skills/ibgib-create-app-witness/templates/witness/app/app-v1.mts.template

@@ -0,0 +1,124 @@
+import {
+    extractErrorMsg, pretty,
+} from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
+import { IbGibAddr, Ib, TransformResult } from '@ibgib/ts-gib/dist/types.mjs';
+import { IbGib_V1, IbGibRel8ns_V1 } from '@ibgib/ts-gib/dist/V1/types.mjs';
+import { getIbGibAddr } from '@ibgib/ts-gib/dist/helper.mjs';
+import { Factory_V1 as factory } from '@ibgib/ts-gib/dist/V1/factory.mjs';
+import { AppBase_V1 } from '@ibgib/core-gib/dist/witness/app/app-base-v1.mjs';
+import { WITNESS_CONTEXT_REL8N_NAME } from '@ibgib/core-gib/dist/witness/witness-constants.mjs';
+import { ROOT } from '@ibgib/ts-gib/dist/V1/constants.mjs';
+
+import { GLOBAL_LOG_A_LOT, APP_CONFIG } from '../../../constants.mjs';
+import {
+    {{APP_CLASSNAME}}Data_V1, {{APP_CLASSNAME}}Rel8ns_V1, {{APP_CLASSNAME}}IbGib_V1,
+} from './{{APP_DIR_NAME}}-types.mjs';
+import {
+    isRequestComment,
+} from './{{APP_DIR_NAME}}-helper.mjs';
+import { PARAM_INFO_INTERACTIVE, {{APP_CLASSNAME_PREFIX}}Command } from './{{APP_DIR_NAME}}-constants.mjs';
+import { RequestCommentData_V1, RequestCommentIbGib_V1 } from '../../../types.mjs';
+
+const logalot = GLOBAL_LOG_A_LOT;
+
+/**
+ * The App Witness for {{APP_HUMAN_NAME}}.
+ * Handles user requests and coordinates the app's internal state.
+ */
+export class {{APP_CLASSNAME}} extends AppBase_V1<
+    // in
+    any, IbGibRel8ns_V1, IbGib_V1<any, IbGibRel8ns_V1>,
+    // out
+    any, IbGibRel8ns_V1, IbGib_V1<any, IbGibRel8ns_V1>,
+    // this
+    {{APP_CLASSNAME}}Data_V1, {{APP_CLASSNAME}}Rel8ns_V1
+> implements {{APP_CLASSNAME}}IbGib_V1 {
+    protected lc: string = `[{{APP_CLASSNAME}}]`;
+
+    constructor(initialData?: {{APP_CLASSNAME}}Data_V1, initialRel8ns?: {{APP_CLASSNAME}}Rel8ns_V1) {
+        super(initialData, initialRel8ns);
+        const lc = `${this.lc}[ctor]`;
+        try {
+            if (logalot) { console.log(`${lc} starting... (I: genuuid)`); }
+            this.initialized = this.initialize();
+        } catch (error) {
+            console.error(`${lc} ${extractErrorMsg(error)}`);
+            throw error;
+        } finally {
+            if (logalot) { console.log(`${lc} complete.`); }
+        }
+    }
+
+    /**
+     * Overridden to handle Request comments (commands).
+     */
+    protected async doNonArg({
+        ibGib,
+    }: {
+        ibGib: IbGib_V1,
+    }): Promise<IbGib_V1 | undefined> {
+        const lc = `${this.lc}[${this.doNonArg.name}]`;
+        try {
+            if (logalot) { console.log(`${lc} starting... (I: genuuid)`); }
+
+            if (isRequestComment({ ibGib })) {
+                return await this.doContextRequestComment({
+                    requestCommentIbGib: ibGib as RequestCommentIbGib_V1
+                });
+            } else {
+                return await super.doNonArg({ ibGib });
+            }
+        } catch (error) {
+            console.error(`${lc} ${extractErrorMsg(error)}`);
+            throw error;
+        } finally {
+            if (logalot) { console.log(`${lc} complete.`); }
+        }
+    }
+
+    /**
+     * Handles the initial bootstrap request or any subsequent command request.
+     */
+    protected async doContextRequestComment({
+        requestCommentIbGib
+    }: {
+        requestCommentIbGib: RequestCommentIbGib_V1
+    }): Promise<IbGib_V1> {
+        const lc = `${this.lc}[${this.doContextRequestComment.name}]`;
+        try {
+            if (logalot) { console.log(`${lc} starting... (I: genuuid)`); }
+            if (logalot) { console.log(`${lc} request: ${pretty(requestCommentIbGib.data)} (I: genuuid)`); }
+
+            const { interpretedArgInfos } = requestCommentIbGib.data!;
+
+            // Handle the initial --interactive bootstrap request
+            if (interpretedArgInfos.some(x => x.name === PARAM_INFO_INTERACTIVE.name)) {
+                await this.initializeContext({
+                    contextIbGib: requestCommentIbGib,
+                    rel8nName: WITNESS_CONTEXT_REL8N_NAME,
+                });
+                
+                console.log(`${this.lc} {{APP_HUMAN_NAME}} initialized and ready. (I: genuuid)`);
+            } else {
+                console.warn(`${lc} other requests not implemented yet. (W: genuuid)`);
+            }
+
+            return ROOT;
+        } catch (error) {
+            console.error(`${lc} ${extractErrorMsg(error)}`);
+            throw error;
+        } finally {
+            if (logalot) { console.log(`${lc} complete.`); }
+        }
+    }
+
+    protected parseAddlMetadataString<TParseResult>({ ib }: { ib: Ib }): TParseResult {
+        return {} as TParseResult;
+    }
+}
+
+/**
+ * Stub factory for app witness creation.
+ */
+export const {{APP_CLASSNAME}}_Factory = {
+}

package/tools/auto-generated-agent-skills/skills/ibgib-create-app-witness/templates/witness/app/constants.mts.template

@@ -0,0 +1,48 @@
+import { RCLIParamInfo } from "@ibgib/helper-gib/dist/rcli/rcli-types.mjs";
+
+/**
+ * Command literal for the app.
+ */
+export type {{APP_CLASSNAME_PREFIX}}Command = 'help' | 'init' | 'quit';
+
+export const {{APP_CLASSNAME_PREFIX}}Command = {
+    help: 'help' as {{APP_CLASSNAME_PREFIX}}Command,
+    init: 'init' as {{APP_CLASSNAME_PREFIX}}Command,
+    quit: 'quit' as {{APP_CLASSNAME_PREFIX}}Command,
+} satisfies { [key: string]: {{APP_CLASSNAME_PREFIX}}Command };
+
+/**
+ * Commands identifiers (including synonyms).
+ */
+export const RCLI_COMMAND_IDENTIFIERS: string[] = [
+    ...Object.values({{APP_CLASSNAME_PREFIX}}Command),
+    'h', 'exit', 'q'
+];
+
+/**
+ * Parameter info for the interactive bootstrap.
+ */
+export const PARAM_INFO_INTERACTIVE: RCLIParamInfo = {
+    name: 'interactive',
+    isFlag: true,
+    argTypeName: 'boolean',
+};
+
+/**
+ * Full parameter info list for command parsing.
+ */
+export const PARAM_INFOS: RCLIParamInfo[] = [
+    PARAM_INFO_INTERACTIVE,
+    {
+        name: 'help',
+        isFlag: true,
+        argTypeName: 'boolean',
+        synonyms: ['h'],
+    },
+    {
+        name: 'quit',
+        isFlag: true,
+        argTypeName: 'boolean',
+        synonyms: ['q', 'exit'],
+    }
+];

package/tools/auto-generated-agent-skills/skills/ibgib-create-app-witness/templates/witness/app/helper.mts.template

@@ -0,0 +1,72 @@
+import {
+    getTimestamp, getUUID,
+} from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
+import { RCLIArgInfo, RCLIParamInfo } from '@ibgib/helper-gib/dist/rcli/rcli-types.mjs';
+import { Factory_V1 as factory } from '@ibgib/ts-gib/dist/V1/factory.mjs';
+import { TransformResult } from '@ibgib/ts-gib/dist/types.mjs';
+import { isComment } from '@ibgib/core-gib/dist/common/comment/comment-helper.mjs';
+import { IbGib_V1 } from '@ibgib/ts-gib/dist/V1/types.mjs';
+
+import { RequestCommentData_V1, RequestCommentIbGib_V1 } from '../../../types.mjs';
+
+/**
+ * Validates that no duplicate parameter identifiers exist in the config.
+ */
+export function validateParamInfos({ paramInfos }: { paramInfos: RCLIParamInfo[] }): string[] {
+    const errors: string[] = [];
+    const identifiers: string[] = [];
+    paramInfos.forEach(p => {
+        const names = [p.name, ...(p.synonyms ?? [])];
+        names.forEach(name => {
+            if (identifiers.includes(name.toLowerCase())) {
+                errors.push(`Duplicate identifier found: ${name} (E: genuuid)`);
+            }
+            identifiers.push(name.toLowerCase());
+        });
+    });
+    return errors;
+}
+
+/**
+ * Minimal stub for arg validation.
+ */
+export function validateArgInfos({ argInfos }: { argInfos: RCLIArgInfo[] }): string | undefined {
+    return undefined;
+}
+
+/**
+ * Detects if an ibgib is a Request Comment (a command).
+ */
+export function isRequestComment({ ibGib }: { ibGib: IbGib_V1 }): boolean {
+    if (!isComment({ ibGib })) { return false; }
+    const data = ibGib.data as RequestCommentData_V1;
+    return !!(data?.args?.length && data?.interpretedArgInfos?.length);
+}
+
+/**
+ * Creates a Request Comment ibgib from raw arguments.
+ */
+export async function createRequestCommentIbGib({
+    args, interpretedArgInfos,
+}: {
+    args: string[],
+    interpretedArgInfos: RCLIArgInfo[],
+}): Promise<TransformResult<RequestCommentIbGib_V1>> {
+    const text = args.join(' ');
+    const data: RequestCommentData_V1 = {
+        uuid: await getUUID(),
+        text,
+        args,
+        interpretedArgInfos,
+        textTimestamp: getTimestamp(),
+    };
+
+    return await factory.firstGen({
+        parentIbGib: factory.primitive({ ib: 'comment' }),
+        ib: `comment ${text.substring(0, 32).replace(/ /g, '_')}`,
+        data,
+        dna: true,
+        tjp: { uuid: true, timestamp: true },
+        nCounter: true,
+    }) as TransformResult<RequestCommentIbGib_V1>;
+}

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

@@ -0,0 +1,38 @@
+import { IbGib_V1, IbGibRel8ns_V1 } from "@ibgib/ts-gib/dist/V1/types.mjs";
+import { AppIbGib_V1 } from "@ibgib/core-gib/dist/witness/app/app-types.mjs";
+
+/**
+ * Data unique to the {{APP_HUMAN_NAME}} App witness.
+ */
+export interface {{APP_CLASSNAME}}Data_V1 extends AppData_V1 {
+    uuid: string;
+    name: string;
+    description: string;
+    classname: string;
+    version: string;
+    icon: string;
+}
+
+export const DEFAULT_{{APP_NAME_UPPER}}_APP_DATA_V1: {{APP_CLASSNAME}}Data_V1 = {
+    uuid: '',
+    name: '{{APP_DIR_NAME}}',
+    description: '{{APP_HUMAN_NAME}} witness',
+    classname: '{{APP_CLASSNAME}}',
+    version: '0.0.1',
+    icon: 'apps-outline',
+};
+
+export const DEFAULT_{{APP_NAME_UPPER}}_APP_REL8NS_V1: {{APP_CLASSNAME}}Rel8ns_V1 | undefined = undefined;
+
+/**
+ * Relationships unique to the {{APP_HUMAN_NAME}} App witness.
+ */
+export interface {{APP_CLASSNAME}}Rel8ns_V1 extends IbGibRel8ns_V1 {
+}
+
+/**
+ * The full IbGib type for the {{APP_HUMAN_NAME}} App witness.
+ */
+export interface {{APP_CLASSNAME}}IbGib_V1
+    extends AppIbGib_V1<{{APP_CLASSNAME}}Data_V1, {{APP_CLASSNAME}}Rel8ns_V1> {
+}

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

@@ -0,0 +1,36 @@
+---
+name: ibgib-create-component
+description: Scaffolds a new reusable ibgib UI component. Generates the component logic (Meta and Instance classes), HTML template, and CSS stylesheet.
+---
+
+# ibgib-create-component
+
+This skill scaffolds a new UI component for an ibgib application. components are implemented as Web Components (Custom Elements) using the `ibgib-web-gib` framework, which provides deep integration with ibgib timelines and real-time updates.
+
+## Goal
+To create a standard, reactive UI component that can be registered with the `ibgib-component-service` and rendered within an app shell.
+
+## Parameters
+Wait for the user to provide or confirm these tokens:
+- `{{COMPONENT_NAME}}`: e.g. `test-component`
+- `{{COMPONENT_TAG_NAME}}`: e.g. `test-app-test-component` (must be kebab-case and include a prefix)
+- `{{COMPONENT_CLASS_PREFIX}}`: e.g. `Test`
+- `{{APP_DIR_NAME}}`: e.g. `test-app`
+- `{{APP_CLASS_PREFIX}}`: e.g. `TestApp` (for helper imports)
+
+## Output Files
+The skill will generate:
+1. `src/components/{{COMPONENT_NAME}}/{{COMPONENT_NAME}}.mts`
+2. `src/components/{{COMPONENT_NAME}}/{{COMPONENT_NAME}}.html`
+3. `src/components/{{COMPONENT_NAME}}/{{COMPONENT_NAME}}.css`
+
+## Usage Instructions
+1. Ensure the `src/components/{{COMPONENT_NAME}}` directory exists.
+2. Generate the files from templates.
+3. Import and register the `{{COMPONENT_CLASS_PREFIX}}ComponentMeta` in your `ShellService`'s `registerComponents()` method.
+
+## Component Lifecycle
+- `initialize(opts)`: Called when the component is first given an ibGib address.
+- `created()`: Called when the element is attached to the DOM. This is where you should query Shadow Root elements.
+- `renderUI()`: Called to update the DOM based on the current `this.ibGib`.
+- `handleContextUpdated()`: Called automatically when the observed ibgib timeline evolves.

package/tools/auto-generated-agent-skills/skills/ibgib-create-component/templates/components/component-name/component.css.template

@@ -0,0 +1,26 @@
+:host {
+    display: block;
+    width: 100%;
+    height: 100%;
+    overflow: hidden;
+}
+
+.component-container {
+    padding: 1.5rem;
+    background: var(--glass-background, rgba(255, 255, 255, 0.1));
+    backdrop-filter: blur(10px);
+    border-radius: 1rem;
+    border: 1px solid var(--border-color, rgba(255, 255, 255, 0.2));
+    color: var(--text-color, #ffffff);
+}
+
+h1 {
+    margin-top: 0;
+    font-size: 1.5rem;
+    color: var(--primary-color, #007aff);
+}
+
+.content {
+    margin-top: 1rem;
+    opacity: 0.8;
+}

package/tools/auto-generated-agent-skills/skills/ibgib-create-component/templates/components/component-name/component.html.template

@@ -0,0 +1,6 @@
+<div id="container" class="component-container">
+    <h1 id="title">IbGib Component</h1>
+    <div class="content">
+        <p>Scaffolded component content goes here.</p>
+    </div>
+</div>