feat: OpenTelemetry LGTM observability, dev tooling, and memoir UX fixes (#31)

* add staging ios app build script

* feat(api): add OpenTelemetry LGTM stack for local observability

Wire OTel traces, metrics, and logs through a collector to Tempo,
Prometheus, and Loki, with custom LLM instrumentation, dev compose overlay,
Grafana provisioning, env templates, and development.sh auto-start.

Co-authored-by: Cursor <cursoragent@cursor.com>

* feat: expand observability, harden dev tooling, and fix expo staging UX

Add business and LLM Prometheus metrics with Grafana dashboards, alerting,
and a metrics verification script. Wire telemetry through adapters and core
LLM paths, and document the local LGTM workflow.

Fix development.sh for macOS bash 3.2, open Grafana and eval-web in Chrome,
and repair eval-web auto-open (unbound EVAL_WEB_BROWSER_SCHEDULED). Merge
internal-eval into the main dev script with improved compose handling.

Require EXPO_PUBLIC_* at build time, improve iOS HTTP ATS for staging IPs,
show memoir empty state instead of load errors when no chapters exist, and
add jest env setup plus chapter list response normalization.

Co-authored-by: Cursor <cursoragent@cursor.com>

* chore: enable Grafana Assistant Cursor plugin

Co-authored-by: Cursor <cursoragent@cursor.com>

* fix: memoir empty state and repair withdrawn 0020_chapters_book_id stamp

Show empty memoir UI when the chapter list succeeds with no items; treat auth/404 as non-fatal. Extend alembic revision repair so local dev DBs stamped with the removed 0020_chapters_book_id migration can roll back and upgrade to 0019.

Co-authored-by: Cursor <cursoragent@cursor.com>

---------

Co-authored-by: Kevin <kevin@brighteng.org>
Co-authored-by: Cursor <cursoragent@cursor.com>

app-expo/plugins/withIosInsecureHttp.js

@@ -1,43 +1,81 @@
 // @ts-check
 /**
- * Allow HTTP / WS to staging API host via App Transport Security exception.
+ * Allow HTTP / WS to staging API hosts via App Transport Security.
  *
  * Enabled when EXPO_PUBLIC_API_URL uses http:// (same rule as Android cleartext).
- * Host is parsed from the URL so IP:port staging endpoints work without hard-coding.
+ * Collects hosts from both API and WS URLs (IP:port staging often differs only by scheme).
  */
 const { withInfoPlist } = require('@expo/config-plugins');
 
 /**
+ * @param {string | undefined} raw
  * @returns {string | null}
  */
-function getHttpExceptionHost() {
-  const raw = process.env.EXPO_PUBLIC_API_URL ?? '';
-  if (!raw.startsWith('http://')) {
+function insecureHttpHostFromUrl(raw) {
+  if (!raw || !raw.startsWith('http://')) {
     return null;
   }
   try {
-    return new URL(raw).hostname;
+    return new URL(raw).hostname || null;
   } catch {
     return null;
   }
 }
 
+/**
+ * @param {string | undefined} raw
+ * @returns {string | null}
+ */
+function insecureWsHostFromUrl(raw) {
+  if (!raw || !raw.startsWith('ws://')) {
+    return null;
+  }
+  try {
+    return new URL(raw).hostname || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * @param {string | undefined} apiUrl
+ * @param {string | undefined} wsUrl
+ * @returns {string[]}
+ */
+function collectInsecureHosts(apiUrl, wsUrl) {
+  const hosts = new Set(
+    [insecureHttpHostFromUrl(apiUrl), insecureWsHostFromUrl(wsUrl)].filter(
+      (h) => typeof h === 'string' && h.length > 0,
+    ),
+  );
+  return [...hosts];
+}
+
+/**
+ * @param {string} host
+ */
+function isIpv4Literal(host) {
+  return /^\d{1,3}(\.\d{1,3}){3}$/u.test(host);
+}
+
 /**
  * @param {import('expo/config').ExpoConfig} config
- * @param {{ enabled?: boolean }} props
+ * @param {{ enabled?: boolean; apiUrl?: string; wsUrl?: string }} props
  */
 function withIosInsecureHttp(config, props = {}) {
   const enabled = props.enabled ?? false;
+  const apiUrl = props.apiUrl ?? process.env.EXPO_PUBLIC_API_URL ?? '';
+  const wsUrl = props.wsUrl ?? process.env.EXPO_PUBLIC_WS_URL ?? '';
 
   return withInfoPlist(config, (mod) => {
     if (!enabled) {
       return mod;
     }
 
-    const host = getHttpExceptionHost();
-    if (!host) {
+    const hosts = collectInsecureHosts(apiUrl, wsUrl);
+    if (hosts.length === 0) {
       console.warn(
-        '[withIosInsecureHttp] enabled but EXPO_PUBLIC_API_URL has no http host; skipping ATS exception.',
+        '[withIosInsecureHttp] enabled but no http/ws hosts found in apiUrl/wsUrl; skipping ATS exception.',
       );
       return mod;
     }
@@ -45,17 +83,32 @@ function withIosInsecureHttp(config, props = {}) {
     const existing = mod.modResults.NSAppTransportSecurity ?? {};
     const existingDomains = existing.NSExceptionDomains ?? {};
 
+    /** @type {Record<string, object>} */
+    const exceptionDomains = { ...existingDomains };
+
+    for (const host of hosts) {
+      exceptionDomains[host] = {
+        NSExceptionAllowsInsecureHTTPLoads: true,
+        // IP literals have no subdomains; false avoids odd ATS behavior on some iOS versions.
+        NSIncludesSubdomains: !isIpv4Literal(host),
+        NSExceptionRequiresForwardSecrecy: false,
+      };
+    }
+
     mod.modResults.NSAppTransportSecurity = {
       ...existing,
-      NSExceptionDomains: {
-        ...existingDomains,
-        [host]: {
-          NSExceptionAllowsInsecureHTTPLoads: true,
-          NSIncludesSubdomains: true,
-        },
-      },
+      /**
+       * Staging often uses bare IP:port HTTP. Domain exceptions alone can fail on
+       * newer iOS builds; allow cleartext while this plugin is enabled (http:// API only).
+       */
+      NSAllowsArbitraryLoads: true,
+      NSExceptionDomains: exceptionDomains,
     };
 
+    console.log(
+      `[withIosInsecureHttp] ATS cleartext enabled for host(s): ${hosts.join(', ')}`,
+    );
+
     return mod;
   });
 }