@ibgib/node-gib 0.0.10 → 0.0.14

package/src/email/email-service.respec.mts

@@ -0,0 +1,134 @@
+import { iReckon, ifWe, respecfully } from '@ibgib/helper-gib/dist/respec-gib/respec-gib.mjs';
+import { createAwsSigV4Headers } from './aws/aws-sigv4-helper.mjs';
+import { EmailReceiverAws } from './aws/email-receiver-aws.mjs';
+import { formatEmailAddress, formatRawMimeString, parseEmailAddress, parseRawMimeHeaders, validateEmail } from './email-helpers.mjs';
+import { EmailSenderMock } from './mock/email-sender-mock.mjs';
+
+const sir = `[${import.meta.url}]`;
+
+await respecfully(sir, 'Email Infrastructure & Drivers', async () => {
+
+    await ifWe(sir, 'validate email addresses accurately using validateEmail', async () => {
+        iReckon(sir, validateEmail('user@example.com')).asTo('valid email').isGonnaBe(true);
+        iReckon(sir, validateEmail('user.name+tag@domain.co.uk')).asTo('valid tagged email').isGonnaBe(true);
+        iReckon(sir, validateEmail('invalid-email')).asTo('invalid format without @').isGonnaBe(false);
+        iReckon(sir, validateEmail('user@')).asTo('missing domain').isGonnaBe(false);
+        iReckon(sir, validateEmail('')).asTo('empty string').isGonnaBe(false);
+    });
+
+    await ifWe(sir, 'parse and format email addresses correctly', async () => {
+        const parsed1 = parseEmailAddress('Alice <alice@example.com>');
+        iReckon(sir, parsed1.address).asTo('parsed address').isGonnaBe('alice@example.com');
+        iReckon(sir, parsed1.name).asTo('parsed name').isGonnaBe('Alice');
+
+        const formatted = formatEmailAddress({ name: 'Bob', address: 'bob@example.com' });
+        iReckon(sir, formatted).asTo('formatted address').isGonnaBe('"Bob" <bob@example.com>');
+    });
+
+    await ifWe(sir, 'format and parse raw MIME headers and strings', async () => {
+        const mimeStr = formatRawMimeString({
+            from: { name: 'Sender', address: 'sender@example.com' },
+            to: ['receiver@example.com'],
+            subject: 'Test Subject',
+            textBody: 'Hello World',
+        });
+
+        const headers = parseRawMimeHeaders(mimeStr);
+        iReckon(sir, headers['From']).asTo('MIME From header').isGonnaBe('"Sender" <sender@example.com>');
+        iReckon(sir, headers['Subject']).asTo('MIME Subject header').isGonnaBe('Test Subject');
+    });
+
+    await ifWe(sir, 'dispatch emails using EmailSenderMock and maintain history', async () => {
+        const mockSender = new EmailSenderMock();
+        mockSender.clearSentEmails();
+
+        const result = await mockSender.sendEmail({
+            from: 'test@example.com',
+            to: ['target@example.com'],
+            subject: 'Mock Subject',
+            textBody: 'Mock body',
+        });
+
+        iReckon(sir, result.success).asTo('mock send result success').isGonnaBe(true);
+        iReckon(sir, Boolean(result.messageId)).asTo('mock messageId generated').isGonnaBe(true);
+
+        const sent = mockSender.getSentEmails();
+        iReckon(sir, sent.length).asTo('sent emails count').isGonnaBe(1);
+        iReckon(sir, sent[0].subject).asTo('sent email subject').isGonnaBe('Mock Subject');
+
+        // Verify failure mode
+        mockSender.shouldFail = true;
+        const failResult = await mockSender.sendEmail({
+            from: 'test@example.com',
+            to: ['target@example.com'],
+            subject: 'Fail Subject',
+            textBody: 'Fail body',
+        });
+        iReckon(sir, failResult.success).asTo('mock send failure result success').isGonnaBe(false);
+    });
+
+    await ifWe(sir, 'calculate valid AWS SigV4 headers with createAwsSigV4Headers', async () => {
+        const sigResult = createAwsSigV4Headers({
+            method: 'POST',
+            url: 'https://email.us-east-1.amazonaws.com/',
+            region: 'us-east-1',
+            service: 'ses',
+            accessKeyId: 'AKIAIOSFODNN7EXAMPLE',
+            secretAccessKey: 'wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY',
+            body: 'Action=SendEmail&Version=2010-12-01',
+            timestamp: new Date('2026-07-30T18:00:00.000Z'),
+        });
+
+        iReckon(sir, sigResult.amzDate).asTo('formatted X-Amz-Date').isGonnaBe('20260730T180000Z');
+        iReckon(sir, sigResult.headers['Host']).asTo('Host header').isGonnaBe('email.us-east-1.amazonaws.com');
+        iReckon(sir, sigResult.authorization.startsWith('AWS4-HMAC-SHA256 Credential=AKIAIOSFODNN7EXAMPLE/20260730/us-east-1/ses/aws4_request')).asTo('authorization header credential prefix').isGonnaBe(true);
+        iReckon(sir, Boolean(sigResult.signature)).asTo('signature computed').isGonnaBe(true);
+    });
+
+    await ifWe(sir, 'parse SES webhook payloads and evaluate spam verdicts into inbox/junk folders', async () => {
+        const receiver = new EmailReceiverAws();
+
+        // Pass verdict payload
+        const passPayload = {
+            mail: {
+                messageId: 'msg-pass-123',
+                source: 'alice@example.com',
+                destination: ['bob@example.com'],
+                commonHeaders: { subject: 'Clean Mail' },
+                timestamp: '2026-07-30T18:00:00Z',
+            },
+            receipt: {
+                spamVerdict: { status: 'PASS' },
+                virusVerdict: { status: 'PASS' },
+                spfVerdict: { status: 'PASS' },
+                dkimVerdict: { status: 'PASS' },
+            },
+            content: 'Clean body',
+        };
+
+        const parsedPass = await receiver.parseInboundPayload(passPayload);
+        iReckon(sir, parsedPass.folder).asTo('clean email folder').isGonnaBe('inbox');
+        iReckon(sir, parsedPass.from.address).asTo('parsed from address').isGonnaBe('alice@example.com');
+        iReckon(sir, parsedPass.subject).asTo('parsed subject').isGonnaBe('Clean Mail');
+
+        // Fail verdict payload
+        const failPayload = {
+            mail: {
+                messageId: 'msg-spam-456',
+                source: 'spammer@badsite.com',
+                destination: ['bob@example.com'],
+                commonHeaders: { subject: 'Buy Cheap Stuff' },
+            },
+            receipt: {
+                spamVerdict: { status: 'FAIL' },
+                virusVerdict: { status: 'PASS' },
+                spfVerdict: { status: 'FAIL' },
+                dkimVerdict: { status: 'PASS' },
+            },
+        };
+
+        const parsedFail = await receiver.parseInboundPayload(failPayload);
+        iReckon(sir, parsedFail.folder).asTo('spam email folder').isGonnaBe('junk');
+    });
+
+});

package/src/email/email-types.mts

@@ -0,0 +1,59 @@
+/**
+ * Interfaces and types for email architecture in node-gib.
+ */
+
+export interface EmailAddress {
+    address: string;
+    name?: string;
+}
+
+export interface OutboundEmail {
+    from: EmailAddress | string;
+    to: (EmailAddress | string)[];
+    cc?: (EmailAddress | string)[];
+    bcc?: (EmailAddress | string)[];
+    subject: string;
+    textBody?: string;
+    htmlBody?: string;
+    replyTo?: EmailAddress | string;
+    headers?: Record<string, string>;
+}
+
+export interface EmailSpamVerdicts {
+    spamVerdict: 'PASS' | 'FAIL' | 'GRAY' | string;
+    virusVerdict?: 'PASS' | 'FAIL' | 'GRAY' | string;
+    spfVerdict?: 'PASS' | 'FAIL' | 'GRAY' | string;
+    dkimVerdict?: 'PASS' | 'FAIL' | 'GRAY' | string;
+    dmarcVerdict?: 'PASS' | 'FAIL' | 'GRAY' | string;
+}
+
+export interface InboundEmail {
+    messageId: string;
+    from: EmailAddress;
+    to: EmailAddress[];
+    cc?: EmailAddress[];
+    subject: string;
+    textBody?: string;
+    htmlBody?: string;
+    rawMime?: string;
+    receivedAt: string;
+    spamVerdicts?: EmailSpamVerdicts;
+    folder?: 'inbox' | 'junk' | string;
+    headers?: Record<string, string>;
+}
+
+export interface EmailSendResult {
+    success: boolean;
+    messageId?: string;
+    error?: string;
+    statusCode?: number;
+}
+
+export interface EmailSender {
+    sendEmail(email: OutboundEmail): Promise<EmailSendResult>;
+}
+
+export interface EmailReceiver {
+    parseInboundPayload(payload: any): Promise<InboundEmail>;
+    evaluateSpamVerdicts(verdicts: EmailSpamVerdicts): 'inbox' | 'junk';
+}

package/src/email/index.mts

@@ -0,0 +1,11 @@
+/**
+ * Email infrastructure module exports.
+ */
+
+export * from './email-constants.mjs';
+export * from './email-types.mjs';
+export * from './email-helpers.mjs';
+export * from './email-sender.mjs';
+export * from './email-receiver.mjs';
+export * from './aws/index.mjs';
+export * from './mock/index.mjs';

package/src/email/mock/email-sender-mock.mts

@@ -0,0 +1,54 @@
+/**
+ * In-memory mock implementation of EmailSenderBase for unit testing.
+ */
+
+import { EmailSenderBase } from '../email-sender.mjs';
+import { EmailSendResult, OutboundEmail } from '../email-types.mjs';
+
+export class EmailSenderMock extends EmailSenderBase {
+    private sentEmails: OutboundEmail[] = [];
+    public shouldFail: boolean = false;
+    public failureMessage: string = 'Mock send failure';
+
+    async sendEmail(email: OutboundEmail): Promise<EmailSendResult> {
+        try {
+            this.validateOutboundEmail(email);
+
+            if (this.shouldFail) {
+                return {
+                    success: false,
+                    error: this.failureMessage,
+                    statusCode: 500,
+                };
+            }
+
+            this.sentEmails.push({ ...email });
+            const messageId = `mock-msg-${Date.now()}-${this.sentEmails.length}`;
+
+            return {
+                success: true,
+                messageId,
+                statusCode: 200,
+            };
+        } catch (error: any) {
+            return {
+                success: false,
+                error: error?.message || String(error),
+            };
+        }
+    }
+
+    /**
+     * Gets array of all emails sent through this mock sender.
+     */
+    getSentEmails(): OutboundEmail[] {
+        return [...this.sentEmails];
+    }
+
+    /**
+     * Clears recorded sent emails.
+     */
+    clearSentEmails(): void {
+        this.sentEmails = [];
+    }
+}

package/src/email/mock/index.mts

@@ -0,0 +1,5 @@
+/**
+ * Mock email driver exports.
+ */
+
+export * from './email-sender-mock.mjs';

package/src/index.mts

@@ -0,0 +1,41 @@
+/**
+ * @module @ibgib/node-gib
+ *
+ * Node.js-specific ibgib witnesses, filesystem spaces, and serve-gib microframework.
+ */
+
+export * from './constants.mjs';
+export * from './foo.mjs';
+export * from './helpers.mjs';
+export * from './types.mjs';
+
+// serve-gib microframework
+export * from './serve-gib/index.mjs';
+
+// email infrastructure
+export {
+    DEFAULT_EMAIL_CHARSET,
+    EMAIL_MODE_AWS,
+    EMAIL_MODE_MOCK,
+    DEFAULT_AWS_REGION,
+    DEFAULT_AWS_SES_ENDPOINT,
+    DEFAULT_AWS_SERVICE,
+    VERDICT_PASS,
+    VERDICT_FAIL,
+    VERDICT_GRAY,
+    FOLDER_INBOX,
+    FOLDER_JUNK,
+    parseEmailAddress,
+    formatEmailAddress,
+    parseRawMimeHeaders,
+    formatRawMimeString,
+    validateEmail,
+    validateEmailAddress,
+    EmailSenderBase,
+    EmailReceiverBase,
+    createAwsSigV4Headers,
+    EmailSenderAws,
+    EmailReceiverAws,
+    EmailSenderMock,
+} from './email/index.mjs';
+export type * from './email/email-types.mjs';

package/src/respec-gib.node.mts

@@ -134,7 +134,7 @@ if (respecGib.errorMsgs.length === 0) {
  * @param found respec paths already found (used in recursive calls)
  * @returns list of all respec paths according to the respec regexp constant {@link RESPEC_FILE_REG_EXP}
  */
-async function getRespecFileFullPaths(dirPath: string, found: string[]): Promise<string[]> {
+async function getRespecFileFullPaths(dirPath: string, found: string[] = []): Promise<string[]> {
     const lc = `[${getRespecFileFullPaths.name}][${dirPath}]`;
     try {
         if (logalot) { console.log(`${lc} starting... (I: 16026290523925f79ba1933847e2a623)`); }
@@ -154,13 +154,12 @@ async function getRespecFileFullPaths(dirPath: string, found: string[]): Promise
             }
         });
 
-        found = found.concat(files);
+        found.push(...files);
         for (let i = 0; i < dirs.length; i++) {
-            const subfound = await getRespecFileFullPaths(dirs[i], found);
-            found = found.concat(subfound);
+            await getRespecFileFullPaths(dirs[i], found);
         }
         return Array.from(new Set(found)); // unique
-    } catch (error) {
+    } catch (error: any) {
         console.error(`${lc} ${error.message}`);
         throw error;
     } finally {

package/src/serve-gib/CHANGELOG.md

@@ -0,0 +1,34 @@
+# serve-gib changelog
+
+_note: as you implement features/fixes/etc., please document them here under the "Working Version" section._
+
+## Working Version
+
+* refactor: relocated `serve-gib` microframework into `@ibgib/node-gib`
+  * Relocated microframework, pipeline orchestrator, and route handlers into `@ibgib/node-gib/src/serve-gib/`.
+  * Added `getStandardServeGibHandlers(opts)` preset helper function in `@ibgib/node-gib/dist/serve-gib/index.mjs`.
+  * Exported complete handler suite (`HealthHandler`, `IbGibGetHandler`, `IbGibPostHandler`, `KeystoneGenesisHandler`, `KeystoneEvolveHandler`, `SsoConfigHandler`, `SsoLinkHandler`, `SsoLoginHandler`, `StaticFileHandler`, `SyncUpgradeHandler`, `ErrorHandler`).
+
+* impl: initial core infrastructure
+  * defined `RouteInfo`, `ResponseResult`, and `ServeGibHandler` foundational types.
+  * implemented `ServeGib_V1` with pipeline-based request processing.
+  * added robust `try..catch..finally` pattern with built-in access logging and timing.
+* impl: handler "pit of success" plumbing
+  * implemented `ServeGibHandlerBase` abstract class to reduce boilerplate.
+  * automated route matching via `canHandleRoute` and `regex` properties.
+  * implemented `handleRouteImpl` pattern to separate plumbing from business logic.
+  * added generic `TQueryParams` support with automated parsing via `parseQueryParams`.
+* feat: hierarchical handler organization
+  * established folder-based grouping mirroring URL paths (e.g., `handlers/api/ibgib/`).
+  * enforced "one handler per hard route" and "one handler per file" architectural guidelines.
+* feat: concrete core handlers
+  * `HealthHandler`: Simple liveness probe.
+  * `IbGibHandler`: Single ibGib address resolution.
+  * `IbGibGraphHandler`: Complex graph/BFS retrieval.
+  * `KeystoneHandler`: Genesis and evolution turn persistence.
+  * `StaticFileHandler`: High-performance asset serving with SPA history fallback.
+  * `ErrorHandler`: Standardized 404 and fatal error reporting.
+* docs: architectural guidance
+  * created `README.md` with detailed guidance on handler philosophy and plumbing usage.
+* test: validation suite
+  * implemented `serve-gib.respec.mts` verifying orchestrator pipeline and `RouteInfo` construction.

package/src/serve-gib/README.md

@@ -0,0 +1,77 @@
+# serve-gib Microframework
+
+A minimalist, high-observability HTTP microframework for ibgib servers, hosted within `@ibgib/node-gib`.
+
+---
+
+## 🚀 Quickstart & Standard Presets
+
+Downstream Node.js server applications (such as `space-gib`) can instantiate a fully functional ibgib server using `getStandardServeGibHandlers(opts)` preset helper exported from `@ibgib/node-gib`:
+
+```typescript
+import { ServeGib_V1, getStandardServeGibHandlers } from '@ibgib/node-gib/dist/serve-gib/index.mjs';
+
+const handlers = await getStandardServeGibHandlers({
+    dataDir: process.env.DATA_DIR ?? './data',
+    clientDir: process.env.CLIENT_DIR ?? './dist/client',
+    ssoServerKdfSecret: process.env.SSO_SERVER_KDF_SECRET,
+    googleClientId: process.env.GOOGLE_CLIENT_ID,
+});
+
+const server = new ServeGib_V1({ handlers, port: 3000 });
+await server.listen();
+```
+
+---
+
+## 🏛️ Architecture & Guidance
+
+### 1. Handler Philosophy
+*   **One handler per "hard" route**: A handler should correspond to a unique URL path pattern, disregarding query parameters.
+*   **One regex per handler**: Concrete handlers should ideally define a single `regex` property for routing.
+*   **One handler per file**: Each route handler should live in its own file within the `handlers/` directory (e.g., `handlers/api/health.handler.mts`).
+  * The subfolders should match the hard route of the handler, e.g., `api/ibgib` route should be in the `handlers/api/ibgib` subfolder.
+
+### 2. The "Pit of Success" Plumbing
+The `ServeGibHandlerBase` class provides built-in plumbing to reduce boilerplate:
+*   **`handleRoute` (Plumbing)**: Automatically checks `canHandleRoute`, parses query parameters, and provides a top-level `try..catch` block for logging and error reporting.
+*   **`handleRouteImpl` (Implementation)**: This is where the core logic of the handler resides.
+*   **`canHandleRoute`**: Defaults to a regex match on `info.pathname`. Override this for more complex routing logic.
+
+### 3. Query Parameters
+Query parameters are handled via the `parseQueryParams` method in the base class.
+*   By default, it parses URL search params into a key-value object.
+*   Handlers can override this method to perform custom parsing or validation (e.g., parsing JSON strings from query params).
+*   The base class is generic: `ServeGibHandlerBase<TQueryParams = any>`.
+
+### 4. RouteInfo
+The `RouteInfo` object provides an enriched view of the incoming request:
+*   `decodedPathSegments`: Pre-split and decoded path parts.
+*   `protocol`, `method`, `body`: Basic HTTP info.
+*   `queryParams`: The result of the handler's `parseQueryParams` call.
+
+---
+
+## ⚙️ Pipeline Order & Built-In Handlers
+
+The `ServeGib_V1` executes handlers in the order they are provided in the `handlers` array. The first handler to return a non-undefined `ResponseResult` wins.
+*   **Tip**: Order specific routes (like `/api/ibgib/graph`) before more general ones (like `/api/ibgib`).
+*   **Built-in Handlers**:
+    * `HealthHandler`: Liveness probe (`GET /api/health`).
+    * `IbGibGetHandler` / `IbGibPostHandler`: Single ibGib retrieval and mutation (`GET/POST /api/ibgib`).
+    * `KeystoneGenesisHandler` / `KeystoneEvolveHandler`: Keystone genesis & timeline evolution.
+    * `SsoConfigHandler` / `SsoLinkHandler` / `SsoLoginHandler`: SSO identity endpoints.
+    * `StaticFileHandler`: SPA asset serving with index fallback.
+    * `SyncUpgradeHandler`: WebSocket sync protocol.
+    * `ErrorHandler`: Final catch-all for 404s and fatal errors.
+
+---
+
+## 🐳 Docker / Server Resilience Note
+When deploying or running this service within a Docker environment, specify a restart policy:
+```yaml
+services:
+  space-gib:
+    restart: unless-stopped
+```
+This ensures auto-recovery if the node process restarts due to unhandled network events (such as raw TCP socket `ECONNRESET` exceptions from client refreshes).

package/src/serve-gib/SERVE_REFACTOR_IMPLEMENTATION.md

@@ -0,0 +1,112 @@
+# serve-gib Refactoring & Relocation Implementation Guide & Diary
+
+This document serves as the persistent architectural roadmap, environmental context guide, implementation diary, and active TODO list for moving `serve-gib` into `@ibgib/node-gib` and DRYing out `space-gib` server/client components.
+
+---
+
+## 1. Environment & Operational Context
+
+* **Environment**: Windows OS environment.
+  * *Pathing Note*: Windows backslashes (`\`) may appear in local shell paths or UI references, but all code imports, config paths, and TS/JS references must use standard forward slashes (`/`).
+* **Token & Testing Constraint**:
+  * **STRICT RULE**: NO automated agentic browser testing (e.g. Playwright, Puppeteer, Selenium) is permitted during development or verification.
+  * **Rationale**: Specifically avoids massive LLM token consumption resulting from screenshot/image generation during automated agentic browser runs. All UI/browser verification must be performed manually by the user or verified via fast microtests.
+* **Build System Mechanics**:
+  * The monorepo uses a custom build system located under `/build`.
+  * **Dependency Build Chains**:
+    * Changes in `core-gib` require building downstream packages: `npm run chain:build:core-gib` (`build:core-gib` -> `build:web-gib` -> `build:node-gib` -> `build:space-gib`).
+    * Changes in `web-gib` require: `npm run chain:build:web-gib` (`web-gib` -> `space-gib`).
+    * Changes in `node-gib` use chain build script: `npm run chain:build:node-gib` (`build:node-gib` -> `build:space-gib`).
+* **Testing Framework (`respec-gib`)**:
+  * All unit and integration tests use ibgib's custom microtesting framework (`respec-gib`), located in `@ibgib/helper-gib/dist/respec-gib`.
+  * **Commands**:
+    * Run node-gib tests: `npm run test:node-gib`
+    * Run core-gib tests: `npm run test:core-gib`
+    * Run space-gib tests: `npm run test:space-gib`
+  * **Structure**:
+    * `respecfully`: Outer suite block (async, must `await`).
+    * `ifWe`: Test case block (async, must `await`).
+    * `ifWeMight`: Focused test case (async, equivalent to `fit` / `it.only`).
+    * `iReckon`: Synchronous assertion fluent API (`willEqual`, `isGonnaBe`, `isGonnaBeTrue`, `includes`, etc.).
+  * Test runner scripts exist per library/app (e.g. `libs/node-gib/src/respec-gib.node.mts`).
+
+---
+
+## 2. Project Architecture & Strategy
+
+### Two Primary Phases
+
+1. **Phase 1: Server Refactoring & `serve-gib` Migration** [COMPLETE]
+   * Relocate `serve-gib` microframework from `apps/space-gib/src/server/serve-gib` into `libs/node-gib`.
+   * Package built-in handlers (`HealthHandler`, `IbGibHandler`, `KeystoneGenesisHandler`, `KeystoneEvolveHandler`, `KeystonePostHandler`, `KeystoneGetHandler`, `SsoLinkHandler`, `SsoLoginHandler`, `SsoConfigHandler`, `StaticFileHandler`, `SyncUpgradeHandler`, `ErrorHandler`).
+   * Provide a clean, strongly-typed TypeScript configuration API via `.mts` options and preset helpers (`getStandardServeGibHandlers(...)`), combining with runtime `.env` / `process.env` configuration.
+   * Support handler subclassing or custom handler arrays for app-specific endpoints.
+   * Refactor `apps/space-gib/src/server/server.mts` to be a clean, minimal consumer of `@ibgib/node-gib`.
+
+2. **Phase 2: Client UI Component Refactoring & DRYing** [COMPLETE]
+   * Extract reusable UI components (`identity-header`, `identity-manager`, `keystone-creator`, `keystone-details`, `keystone-scrubber`) from `apps/space-gib/src/client/components/` into `@ibgib/web-gib`.
+   * **API Bridge Abstraction**: Introduced `IbGibApiBridge` base class and `getApiBridge()/setApiBridge()` accessors in `@ibgib/web-gib`, letting downstream apps extend or configure their own REST bridge.
+   * **Constructor & State Architecture**:
+     * Components use `getComponentCtorArg(globalThisKey?)` directly from `@ibgib/web-gib/dist/app-bootstrap/init-orchestration.mjs` to decouple constructor dependencies.
+     * Components use `@ibgib/web-gib` ambient context (`getIbGibGlobalThis()`) and event constants (`EVENT_IBGIB_UI_MESSAGE`, `EVENT_IBGIB_IDENTITY_CHANGED`, `EVENT_IBGIB_IDENTITY_REQUEST_CHANGE`), avoiding string literals.
+   * Transformed `space-gib` into a clean, boilerplate template application consuming `@ibgib/web-gib` identity components via single-line `registerStandardIdentityComponents()` call.
+
+---
+
+## 3. Configuration Design (.env + .mts Programmatic Options)
+
+Rather than maintaining a separate JSON schema/config system, we leverage:
+1. **Runtime Environment Variables (`.env`)**: Standard environment variables (`PORT`, `DATA_DIR`, `CLIENT_DIR`, `SSO_SERVER_KDF_SECRET`, `SESSION_SECRET`, `GOOGLE_CLIENT_ID`) read via `process.env`.
+2. **TypeScript Options & Presets (`.mts`)**: Programmatic, strongly-typed `ServeGibOptions` passed to `ServeGib_V1` or helper functions like `getStandardServeGibHandlers(options)`.
+3. **Subclassing / Custom Handlers**: Apps can extend `ServeGibHandlerBase` or `ServeGib_V1` to add custom routes or hooks as needed.
+
+---
+
+## 4. Implementation Checklist & Todo List
+
+### Phase 1: Server Move & `serve-gib` Migration (`libs/node-gib`)
+- [x] **Build System Updates (`package.json`)**:
+  - [x] Update `"chain:build:core-gib"` in root `package.json` to include `build:node-gib`.
+  - [x] Add `"chain:build:node-gib": "npm run build:node-gib && npm run build:space-gib"` to root `package.json`.
+- [x] **Copy & Adapt Files**: Move `serve-gib` source files and server helpers (`bootstrap-helper`, `path-helper`, `path-constants`, `metaspace-nodeindexedspace`) into `libs/node-gib/src/serve-gib/`.
+- [x] **Handler Presets & Options**: Export handler classes and preset helpers (`getStandardServeGibHandlers`) from `@ibgib/node-gib`.
+- [x] **Node-Gib Respec Tests**: Verify `respec-gib` tests in `libs/node-gib` running via `npm run test:node-gib`.
+- [x] **Space-Gib Server Refactor**: Refactor `apps/space-gib/src/server/server.mts` to import `serve-gib` and handlers directly from `@ibgib/node-gib`.
+- [x] **Clean Up Space-Gib Server**: Delete old duplicated `serve-gib` folder and server helper files from `apps/space-gib/src/server/`.
+- [x] **Verification**: Execute `npm run chain:build:node-gib` and verify clean 0-error compilation and bundling of both `node-gib` and `space-gib`.
+
+### Phase 2: Client Component Refactoring (`web-gib` / `space-gib`)
+- [x] **Create `IbGibApiBridge` Base**: Create `IbGibApiBridge` base class and `getApiBridge()`/`setApiBridge()` accessors in `@ibgib/web-gib/src/api/ibgib-api-bridge.mts`.
+- [x] **Audit Client Components**: Inventory components in `apps/space-gib/src/client/components/` (`identity-header`, `identity-manager`, `keystone-creator`, `keystone-details`, `keystone-scrubber`).
+- [x] **Decouple Constructor & Shared State**: Update component constructors to import `getComponentCtorArg()` from `@ibgib/web-gib/dist/app-bootstrap/init-orchestration.mjs`, use `getApiBridge()`, and use `EVENT_IBGIB_UI_MESSAGE` constants.
+- [x] **Migrate Shared UI to `web-gib`**: Move reusable web components to `libs/web-gib/src/ui/component/identity/`.
+- [x] **Export Identity Component Presets**: Add `registerStandardIdentityComponents()` to `@ibgib/web-gib`.
+- [x] **Space-Gib Client Simplification**: Refactor `SpaceGibApiBridge` to extend `IbGibApiBridge` and refactor `apps/space-gib/src/client/` to import identity components from `@ibgib/web-gib`.
+- [x] **Verification**: Run `npm run chain:build:web-gib` and manually verify SPA functionality in browser without automated agentic browser tests.
+
+---
+
+## 5. Implementation Diary & Notes
+
+* **2026-07-22**: Initialized implementation tracking file. Defined operational rules (Windows pathing, no automated browser testing, build chain commands).
+* **2026-07-22 Update**: Streamlined server configuration design to `.env` + `.mts` programmatic options and presets (skipping JSON config/schema). Added `node-gib` to `chain:build:core-gib`, confirmed `npm run test:node-gib` usage, and noted global/shared state handling for Phase 2 client components.
+* **2026-07-22 Phase 1 Execution**:
+  * Relocated `serve-gib` microframework, handlers, and server helpers (`bootstrap-helper`, `path-helper`, `metaspace-nodeindexedspace`) to `libs/node-gib/src/serve-gib/`.
+  * Updated root `package.json` to include `node-gib` in `chain:build:core-gib` and added `chain:build:node-gib`.
+  * Created `getStandardServeGibHandlers(opts)` preset helper function in `libs/node-gib/src/serve-gib/index.mts`.
+  * Updated all relative import depths and resolved `GLOBAL_LOG_A_LOT` export ambiguity.
+  * Refactored `apps/space-gib/src/server/server.mts` to use `@ibgib/node-gib/dist/serve-gib/index.mjs` directly, reducing `server.mts` to under 60 lines of minimal setup code.
+  * Removed legacy duplicated `serve-gib` folder and server helper files from `apps/space-gib/src/server/`.
+  * Verified build with `npm run chain:build:node-gib` — 0 errors, both server and client bundle cleanly.
+* **2026-07-22 Phase 2 Plan & Execution**:
+  * Created `IbGibApiBridge` base class (`libs/web-gib/src/api/ibgib-api-bridge.mts`) with `getApiBridge()`/`setApiBridge()` accessors.
+  * Refactored `SpaceGibApiBridge` to extend `IbGibApiBridge` and register itself on app bootstrap.
+  * Extracted the 5 Keystone Identity UI components (`identity-header`, `identity-manager`, `keystone-creator`, `keystone-details`, `keystone-scrubber`) into `libs/web-gib/src/ui/component/identity/`.
+  * Made `globalThisKey` optional in `getComponentCtorArg()` in `init-orchestration.mts` to decouple constructor initialization.
+  * Replaced all string literals with `EVENT_IBGIB_UI_MESSAGE` and event constants from `@ibgib/web-gib`.
+  * Created `custom.d.ts` in `libs/web-gib/src/` to declare `.html` and `.css` module types for `tsc`.
+  * Updated `build-web-gib.mts` build script to copy `.html` and `.css` component template assets recursively from `src/` to `dist/`.
+  * Added `registerStandardIdentityComponents()` to `@ibgib/web-gib`.
+  * Refactored `apps/space-gib/src/client/ui/shell/space-gib-shell-service.mts` to register identity components in a single line.
+  * Deleted local duplicate component folders from `apps/space-gib/src/client/components/`.
+  * Verified compilation and bundling via `npm run chain:build:web-gib` — 0 errors across web-gib and space-gib!