@ibgib/web-gib 0.0.62 → 0.0.64

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

@@ -0,0 +1,78 @@
+---
+name: ibgib-create-client-identity
+description: Scaffolds drop-in Keystone identity UI Web Components registration and remote Hub sync wiring for an ibgib client application.
+---
+
+# Skill: ibgib-create-client-identity
+
+## What This Skill Does
+
+This skill wires prebuilt Keystone identity UI components and symmetric peer sync into an `ibgib` client application. Downstream applications do not need to build custom authentication screens, passkey genesis flows, or device management dialogs.
+
+This skill automates:
+1. **Component Registration**: Registering all native Web Components from `@ibgib/web-gib/dist/ui/component/identity/index.mjs` in `bootstrap.mts`.
+2. **HTML Integration**: Embedding `<ibgib-identity-manager>`, `<ibgib-keystone-creator>`, `<ibgib-keystone-details>`, or `<ibgib-identity-header>` into the application shell.
+3. **Hub Sync Wiring**: Initializing `SyncWebsocketPeer_V1` and `KeystoneSyncService` using `APP_CONFIG.hubUrl`.
+
+For complete architectural details, refer to [`docs/IBGIB_CLIENT_APPS_GUIDE.md`](file:///c:/Users/billm/antigravity/ibgib/docs/IBGIB_CLIENT_APPS_GUIDE.md).
+
+---
+
+## Pre-Requisites
+- Ensure `ibgib-create-client-app-core` and `ibgib-create-client-app-witness` have been scaffolded.
+
+---
+
+## Integration Steps
+
+### 1. Register Components in `bootstrap.mts`
+Add the following import and invocation to `src/bootstrap.mts` (or `src/client/bootstrap.mts`):
+
+```typescript
+import { registerIdentityComponents } from '@ibgib/web-gib/dist/ui/component/identity/index.mjs';
+
+// Inside your bootstrap / init function:
+registerIdentityComponents();
+```
+
+### 2. Embed Identity Elements in DOM / Shell Template
+Add identity components to `index.html` or inside your main component's HTML template:
+
+```html
+<!-- Header Identity Badge -->
+<header class="app-header">
+    <h1>{{APP_HUMAN_NAME}}</h1>
+    <ibgib-identity-header></ibgib-identity-header>
+</header>
+
+<!-- Main Identity View (shown in Settings or Auth Modal) -->
+<section id="identity-section" class="hidden">
+    <ibgib-identity-manager></ibgib-identity-manager>
+</section>
+```
+
+### 3. Initialize Remote Hub Sync Service
+In `bootstrap.mts` (or an `identity-sync.mts` helper), wire up symmetric sync:
+
+```typescript
+import { KeystoneSyncService, SyncWebsocketPeer_V1 } from '@ibgib/web-gib';
+import { APP_CONFIG } from './config.mjs';
+
+export async function initHubSync({ metaspace, localSpace }: { metaspace: any, localSpace: any }) {
+    const wsUrl = APP_CONFIG.hubUrl.replace(/^http/, 'ws') + '/api/sync';
+    
+    const peerWitness = new SyncWebsocketPeer_V1({
+        url: wsUrl,
+        metaspace,
+        localSpace
+    });
+
+    const syncService = new KeystoneSyncService({
+        peerWitness,
+        metaspace,
+        localSpace
+    });
+
+    return syncService;
+}
+```

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

@@ -0,0 +1,42 @@
+---
+name: ibgib-create-client-shell
+description: Scaffolds the foundational UI Shell for an ibgib client app. Generates the shell service, constants, and types required for UI management and component registration.
+---
+
+# Skill: ibgib-create-client-shell
+
+## What This Skill Does
+
+This skill scaffolds the UI Shell architecture for an `ibgib` client application. The Shell Service acts as a singleton on `globalThis` that manages DOM interactions, handles shell-specific events (e.g. burger menus, window resizing), and coordinates UI activation once the Metaspace and App Witness are initialized.
+
+For full architectural context, refer to [`docs/IBGIB_CLIENT_APPS_GUIDE.md`](file:///c:/Users/billm/antigravity/ibgib/docs/IBGIB_CLIENT_APPS_GUIDE.md).
+
+---
+
+## Parameters (Tokens)
+- `{{APP_NAME}}`: kebab-case (e.g. `test-app`)
+- `{{APP_DIR_NAME}}`: folder name (e.g. `test-app`)
+- `{{APP_CLASSNAME_PREFIX}}`: PascalCase (e.g. `TestApp`)
+- `{{APP_CLASSNAME}}`: e.g. `TestAppApp_V1`
+- `{{APP_HUMAN_NAME}}`: e.g. `Test App`
+- `{{APP_VAR_NAME}}`: camelCase (e.g. `testApp`)
+
+---
+
+## Output Files
+The skill generates:
+1. `src/ui/shell/{{APP_DIR_NAME}}-shell-service.mts` (or `src/client/ui/shell/...`)
+2. `src/ui/shell/{{APP_DIR_NAME}}-shell-constants.mts`
+3. `src/ui/shell/{{APP_DIR_NAME}}-shell-types.mts`
+
+---
+
+## Usage Instructions
+1. Ensure the `src/ui/shell` (or `src/client/ui/shell`) directory exists.
+2. Generate the shell service, constants, and types from templates in `templates/ui/shell/`.
+3. Update `script.mts` to import and call the shell factory:
+   ```typescript
+   import { get{{APP_CLASSNAME_PREFIX}}ShellSvc } from "./ui/shell/{{APP_DIR_NAME}}-shell-service.mjs";
+   get{{APP_CLASSNAME_PREFIX}}ShellSvc();
+   ```
+4. Update `bootstrap.mts` to invoke `get{{APP_CLASSNAME_PREFIX}}ShellSvc().onEngineReady()` inside the `onReady` lifecycle hook.

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

@@ -0,0 +1,50 @@
+---
+name: ibgib-create-server-app
+description: Scaffolds the backend Node.js server for an ibgib full-stack application using serve-gib from @ibgib/node-gib, including WebSocket sync upgrade, Traefik Docker Compose, and server TypeScript configuration.
+---
+
+# Skill: ibgib-create-server-app
+
+## What This Skill Does
+
+Generates the backend server infrastructure for an `ibgib` server application or the server backend of a full-stack project. This includes:
+- **`src/server/server.mts`**: Node.js HTTP/WebSocket server utilizing `serve-gib`, `getStandardServeGibHandlers()`, and `SyncUpgradeHandler`.
+- **`tsconfig.server.json`**: TypeScript compiler configuration targeted for Node.js ESNext.
+- **`Dockerfile`**: Lightweight Alpine container packaging the bundled server and static client SPA.
+- **`docker-compose.yml`**: Local multi-container orchestration behind the Traefik reverse proxy with automatic local HTTPS (`*.localhost` and `local.ibgib.space` SSO loopback).
+
+For architectural context, refer to [`docs/IBGIB_SERVER_APPS_GUIDE.md`](file:///c:/Users/billm/antigravity/ibgib/docs/IBGIB_SERVER_APPS_GUIDE.md).
+
+---
+
+## Token Reference
+
+| Token | Example value | How it's computed |
+|---|---|---|
+| `{{APP_NAME}}` | `my-app` | kebab-case application name |
+| `{{APP_DIR_NAME}}` | `my-app` | Folder name |
+| `{{APP_HUMAN_NAME}}` | `My App` | Natural language name |
+| `{{PORT}}` | `3000` | Server port (default `3000`) |
+| `{{DATA_DIR_REL}}` | `../../.data/my-app-space` | Local storage directory relative to server |
+| `{{LOCAL_DOMAIN}}` | `my-app.localhost` | Local HTTPS subdomain |
+| `{{APP_UUID}}` | `4b810a9c...` | Unique 32-char hex string from `generate-id.js` |
+
+---
+
+## Generation Steps
+
+### 1. Confirm token values
+Derive tokens from the developer's inputs and generate fresh UUIDs using `node .agents/skills/ibgib-create-client-app-core/generate-id.js`.
+
+### 2. Generate files
+Apply token substitutions to templates in `templates/` and write to the target application directory:
+
+| Template file | Output file |
+|---|---|
+| `templates/server.mts.template` | `src/server/server.mts` |
+| `templates/tsconfig.server.json.template` | `tsconfig.server.json` |
+| `templates/Dockerfile.template` | `Dockerfile` |
+| `templates/docker-compose.yml.template` | `docker-compose.yml` (or app service block) |
+
+### 3. Update Build Script
+Ensure the application's `build-[app-name].mts` script configures `tsconfigConfigs` for both client (`tsconfig.json`) and server (`tsconfig.server.json`), and builds the server entry point via `buildServer()`.

package/tools/auto-generated-agent-skills/skills/ibgib-create-server-app/templates/Dockerfile.template

@@ -0,0 +1,14 @@
+FROM node:22-alpine
+WORKDIR /app
+
+# The server is bundled into a single zero-dependency ESM file via esbuild
+COPY dist/server ./server
+
+# Client SPA (served as static files by the node server)
+COPY dist/client ./client
+
+ENV PORT={{PORT}}
+ENV DATA_DIR=/data/{{APP_DIR_NAME}}-space
+
+EXPOSE {{PORT}}
+CMD ["node", "server/server.mjs"]

package/tools/auto-generated-agent-skills/skills/ibgib-create-server-app/templates/docker-compose.yml.template

@@ -0,0 +1,33 @@
+version: '3.8'
+
+services:
+  # ==========================================
+  # {{APP_NAME_UPPER}} SERVICE
+  # ==========================================
+  {{APP_DIR_NAME}}:
+    build: ./apps/{{APP_DIR_NAME}}
+    restart: unless-stopped
+    volumes:
+      - ./apps/{{APP_DIR_NAME}}/.data:/data/{{APP_DIR_NAME}}-space
+      - ./apps/{{APP_DIR_NAME}}/dist/client:/app/client
+      - ./apps/{{APP_DIR_NAME}}/dist/server:/app/server
+    environment:
+      - PORT={{PORT}}
+      - DATA_DIR=/data/{{APP_DIR_NAME}}-space
+      - KEYSTONE_PROFILE_SOVEREIGN_PRIMARY=${KEYSTONE_PROFILE_SOVEREIGN_PRIMARY}
+      - KEYSTONE_PROFILE_SOVEREIGN_SYNC=${KEYSTONE_PROFILE_SOVEREIGN_SYNC}
+      - KEYSTONE_PROFILE_CUSTODIAN_PRIMARY=${KEYSTONE_PROFILE_CUSTODIAN_PRIMARY}
+      - KEYSTONE_PROFILE_CUSTODIAN_SYNC=${KEYSTONE_PROFILE_CUSTODIAN_SYNC}
+      - EMAIL_MODE=${EMAIL_MODE}
+      - SSO_SERVER_KDF_SECRET=${SSO_SERVER_KDF_SECRET}
+      - SESSION_SECRET=${SESSION_SECRET}
+      - GOOGLE_CLIENT_ID=${GOOGLE_CLIENT_ID}
+      - GOOGLE_CLIENT_SECRET=${GOOGLE_CLIENT_SECRET}
+      - GITHUB_CLIENT_ID=${GITHUB_CLIENT_ID}
+      - GITHUB_CLIENT_SECRET=${GITHUB_CLIENT_SECRET}
+    labels:
+      - "traefik.enable=true"
+      - "traefik.http.routers.{{APP_DIR_NAME}}.rule=Host(`{{LOCAL_DOMAIN}}`) || Host(`local.ibgib.space`)"
+      - "traefik.http.routers.{{APP_DIR_NAME}}.entrypoints=websecure"
+      - "traefik.http.routers.{{APP_DIR_NAME}}.tls=true"
+      - "traefik.http.services.{{APP_DIR_NAME}}.loadbalancer.server.port={{PORT}}"

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

@@ -0,0 +1,97 @@
+/**
+ * @module server
+ *
+ * Native Node.js HTTP & WebSocket server for {{APP_NAME}} — using serve-gib from @ibgib/node-gib.
+ */
+
+import { createServer } from 'node:http';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { extractErrorMsg } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
+import {
+    ServeGib_V1,
+    ErrorHandler,
+    SyncUpgradeHandler,
+    canHandleWsUpgrade,
+    handleWsEchoUpgrade,
+    getStandardServeGibHandlers,
+} from '@ibgib/node-gib/dist/serve-gib/index.mjs';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+// ---------------------------------------------------------------------------
+// Config
+// ---------------------------------------------------------------------------
+
+const PORT = parseInt(process.env.PORT ?? '{{PORT}}', 10);
+const DATA_DIR = process.env.DATA_DIR ?? join(__dirname, '{{DATA_DIR_REL}}');
+const CLIENT_DIR = join(__dirname, '../client');
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+async function main(): Promise<void> {
+    const lc = '[{{APP_NAME}} server]';
+    try {
+        console.log(`${lc} starting...`);
+        console.log(`${lc} dataDir: ${DATA_DIR}`);
+
+        const custodianPrimaryProfile = (process.env.KEYSTONE_PROFILE_CUSTODIAN_PRIMARY || '').trim();
+        if (!custodianPrimaryProfile) {
+            throw new Error(`${lc} Fatal Error: KEYSTONE_PROFILE_CUSTODIAN_PRIMARY environment variable is missing or blank. (E: {{APP_UUID}})`);
+        }
+
+        const isProdEnv = process.env.NODE_ENV === 'production';
+        if (isProdEnv && !custodianPrimaryProfile.endsWith('.prod')) {
+            throw new Error(`${lc} Security Violation: Non-production keystone profile '${custodianPrimaryProfile}' is prohibited when NODE_ENV=production. (E: {{APP_UUID}})`);
+        }
+
+        console.log(`${lc} KEYSTONE_PROFILE_CUSTODIAN_PRIMARY: ${custodianPrimaryProfile} (I: {{APP_UUID}})`);
+
+        if (custodianPrimaryProfile.endsWith('.dev')) {
+            console.warn(`\n==========================================================\n⚠️ WARNING: CUSTODIAN KEYSTONE PROFILE IS SET TO DEVELOPMENT ('${custodianPrimaryProfile}')!\nCUSTODIAL KEYSTONES WILL USE LOW-SECURITY DEV PARAMETERS.\nFOR LOCAL TESTING ONLY — DO NOT USE FOR REAL SECRETS OR PRODUCTION DATA!\n==========================================================\n (W: {{APP_UUID}})`);
+        } else if (custodianPrimaryProfile.endsWith('.staging')) {
+            console.info(`${lc} ℹ️ STAGING CUSTODIAN KEYSTONE PROFILE ACTIVE ('${custodianPrimaryProfile}')`);
+        }
+
+        const syncUpgradeHandler = new SyncUpgradeHandler();
+
+        // Initialize serve-gib using standard handler preset from @ibgib/node-gib
+        const serveGib = new ServeGib_V1({
+            port: PORT,
+            dataDir: DATA_DIR,
+            handlers: getStandardServeGibHandlers({ clientDir: CLIENT_DIR }),
+            errorHandler: new ErrorHandler()
+        });
+
+        const server = createServer(async (req, res) => {
+            await serveGib.handleRequest(req, res);
+        });
+
+        // WebSocket upgrade handling for symmetric sync
+        server.on('upgrade', async (req, socket, head) => {
+            const reqCtx = await serveGib.prepareContext(req);
+
+            const isSync = await syncUpgradeHandler.handleUpgrade(reqCtx, socket as any, head);
+
+            if (!isSync && canHandleWsUpgrade(req)) {
+                handleWsEchoUpgrade(req, socket as any, head);
+            } else if (!isSync) {
+                socket.write('HTTP/1.1 404 Not Found\r\n\r\n');
+                socket.destroy();
+            }
+        });
+
+        server.listen(PORT, '0.0.0.0', () => {
+            console.log(`${lc} listening on http://0.0.0.0:${PORT}`);
+        });
+
+    } catch (error) {
+        console.error(`${lc} fatal: ${extractErrorMsg(error)}`);
+        process.exit(1);
+    }
+}
+
+main();

package/tools/auto-generated-agent-skills/skills/ibgib-create-server-app/templates/tsconfig.server.json.template

@@ -0,0 +1,29 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "declaration": false,
+    "declarationMap": false,
+    "sourceMap": false,
+    "rootDir": "./src",
+    "composite": false,
+    "outDir": "./dist/server",
+    "module": "ESNext",
+    "lib": [
+      "ES2022",
+      "ES2023"
+    ],
+    "types": ["node"]
+  },
+  "include": [
+    "src/server/**/*.ts",
+    "src/server/**/*.mts",
+    "src/server/**/*.d.ts",
+    "src/common/**/*.ts",
+    "src/common/**/*.mts"
+  ],
+  "exclude": [
+    "node_modules",
+    "**/*.respec.mts",
+    "./dist/**/*"
+  ]
+}

package/tools/auto-generated-agent-skills/skills/ibgib-implementation-plan/SKILL.md

@@ -36,7 +36,10 @@ Every `[what]_IMPLEMENTATION.md` file MUST follow this high-level structure, ada
 
 ## 🛠️ Build Chain & Environment Setup
 
-*   **Workspace Build Chain**: Required build commands and dependency propagation steps (e.g., `npm run build:core-gib` vs `npm run chain:build:web-gib`).
+*   **Workspace Build Chain**:
+    *   **Local Library Iteration**: When modifying code in a lower-level library (e.g. `libs/core-gib`), run its specific build and test commands (e.g. `npm run build:core-gib` and `npm run test:core-gib`).
+    *   **Downstream Chain Propagation**: After local library changes pass, you MUST propagate changes to downstream dependents by running the appropriate chain build command (e.g. `npm run chain:build:core-gib` or `npm run chain:build:web-gib`).
+    *   **Application Builds**: Build and run downstream applications with `npm run build:[app]` or `npm run watch:[app]` (e.g. `npm run build:space-gib`).
 *   **Environment Configuration**: Required `.env` variables, port settings, or hardware/OS constraints.
 
 ---

package/src/identity/custodian-delegate-helper.mts.bak

@@ -1,7 +0,0 @@
-/**
- * @module identity/custodian-delegate-helper
- *
- * Re-exports from {@link ./device-delegate-helper.mjs} for backward compatibility.
- */
-
-export * from './device-delegate-helper.mjs';

package/src/identity/sso/sso-config-helper.mts.bak

@@ -1,52 +0,0 @@
-import { SsoServerConfig, SsoProviderServerConfig, SsoProviderId } from './sso-types.mjs';
-
-/**
- * Loads the SSO configuration from environment variables.
- * Parses active OAuth2 providers dynamically based on their environment keys.
- */
-export function loadSsoServerConfig(): SsoServerConfig {
-    const ssoServerKdfSecret = process.env.SSO_SERVER_KDF_SECRET;
-    const sessionSecret = process.env.SESSION_SECRET;
-
-    if (!ssoServerKdfSecret) {
-        throw new Error(
-            `SSO_SERVER_KDF_SECRET is missing from environment. (E: 840899ab4fdfd23e89cfae1889cfae12)`
-        );
-    }
-    if (!sessionSecret) {
-        throw new Error(
-            `SESSION_SECRET is missing from environment. (E: bfa899ab4fdfd23e89cfae23)`
-        );
-    }
-
-    const providers: Partial<Record<SsoProviderId, SsoProviderServerConfig>> = {};
-
-    // Load Google Provider if configured
-    if (process.env.GOOGLE_CLIENT_ID && process.env.GOOGLE_CLIENT_SECRET) {
-        providers.google = {
-            providerId: 'google',
-            clientId: process.env.GOOGLE_CLIENT_ID,
-            clientSecret: process.env.GOOGLE_CLIENT_SECRET,
-            tokenUrl: 'https://oauth2.googleapis.com/token',
-            userInfoUrl: 'https://openidconnect.googleapis.com/v1/userinfo',
-            jwksUrl: 'https://www.googleapis.com/oauth2/v3/certs'
-        };
-    }
-
-    // Load GitHub Provider if configured
-    if (process.env.GITHUB_CLIENT_ID && process.env.GITHUB_CLIENT_SECRET) {
-        providers.github = {
-            providerId: 'github',
-            clientId: process.env.GITHUB_CLIENT_ID,
-            clientSecret: process.env.GITHUB_CLIENT_SECRET,
-            tokenUrl: 'https://github.com/login/oauth/access_token',
-            userInfoUrl: 'https://api.github.com/user'
-        };
-    }
-
-    return {
-        ssoServerKdfSecret,
-        sessionSecret,
-        providers
-    };
-}