@almadar/orb 16.9.0 → 17.0.0

package/shells/almadar-shell-hono/packages/server/src/app.ts

@@ -0,0 +1,70 @@
+/**
+ * Hono Application Setup
+ */
+
+import { Hono } from 'hono';
+import { cors } from 'hono/cors';
+import {
+  errorHandler,
+  notFoundHandler,
+  debugEventsRouter,
+  pushRouter,
+  pushServiceWorkerHandler,
+  PUSH_SERVICE_WORKER_PATH,
+  reportsRouter,
+  createHooksRouter,
+  type AppEnv,
+} from '@almadar/server-hono';
+import { hookProviders } from './hooks-providers.js';
+import { broadcastBusEvent } from './sse.js';
+import { registerRoutes } from './routes.js';
+
+export const app = new Hono<AppEnv>();
+
+// Middleware
+app.use('*', cors({ origin: (origin) => origin, credentials: true }));
+
+// Health check
+app.get('/health', (c) => c.json({ status: 'ok' }));
+
+// Debug event bus endpoints (dev-only, no-op in production)
+app.route('/api/debug', debugEventsRouter());
+
+// Web Push surface (browser/push-subscribe): public VAPID key + the shared
+// service worker (root-scoped — a SW's max scope is its own directory).
+app.route('/api/push', pushRouter);
+app.get(PUSH_SERVICE_WORKER_PATH, pushServiceWorkerHandler);
+
+// Inbound webhook ingress (I-19 decision): mounted BEFORE the authenticated
+// /api routes — hook senders (Google Calendar watch channels, e-sign status,
+// banking callbacks) cannot present a Firebase token, so each provider
+// VERIFIES its own signature/channel token and unverified requests get 400.
+// Dispatch = SSE bus broadcast to every connected client, so client circuits'
+// `listens` fire; the cron pull cycle stays the no-client backstop.
+app.route(
+  '/api/hooks',
+  createHooksRouter({
+    // Derived from this app's invoked services (generated hooks-providers.ts, I-26).
+    providers: hookProviders(),
+    dispatch: (event, payload) => {
+      broadcastBusEvent(undefined, {
+        type: 'bus',
+        event,
+        payload,
+        source: { orbital: 'webhook', trait: 'ingress' },
+        timestamp: Date.now(),
+      });
+    },
+  }),
+);
+
+// Register generated routes
+registerRoutes(app);
+
+// Server-side report export (Excel/PDF/CSV). Mounted AFTER registerRoutes so
+// the /api/* auth middleware it registers covers this route too.
+app.route('/api/reports', reportsRouter);
+
+// Error handling
+app.notFound(notFoundHandler);
+app.onError(errorHandler);

package/shells/almadar-shell-hono/packages/server/src/hooks-providers.ts

@@ -0,0 +1,11 @@
+/**
+ * Hook Providers
+ *
+ * Checked-in stub so the template builds standalone in CI; the compiler
+ * overwrites it with the provider map derived from the app's invoked
+ * services × the registry's hook declarations (I-26).
+ */
+
+export function hookProviders() {
+  return {};
+}

package/shells/almadar-shell-hono/packages/server/src/index.ts

@@ -0,0 +1,70 @@
+/**
+ * Server Entry Point
+ */
+
+import { initializeFirebase, env, logger } from '@almadar/server-hono';
+
+// Initialize Firebase before anything else uses it. When no credentials
+// are configured (local dev without FIREBASE_*/FIRESTORE_EMULATOR_HOST),
+// boot anyway — a purely client-side app must still serve.
+try {
+  initializeFirebase();
+} catch (e) {
+  const message = e instanceof Error ? e.message : String(e);
+  // In production the real data source IS Firebase (env.ts refuses to boot with
+  // USE_MOCK_DATA=true there), so swallowing this leaves a server that starts
+  // cleanly and then throws on the first request. Fail at boot instead.
+  if (env.NODE_ENV === 'production') {
+    logger.error(`Firebase is required when NODE_ENV=production — refusing to start: ${message}`);
+    throw e;
+  }
+  logger.warn(`Firebase not configured — auth/db routes disabled: ${message}`);
+}
+
+import { serve } from '@hono/node-server';
+import { validateIntegrationEnv, FirestoreCredentialPersistence } from '@almadar/server-hono';
+import { app } from './app.js';
+import { invokedServices, installTenantCredentialStore } from './services/clients.js';
+
+// Fail fast in production when a required integration credential is missing
+// (see SECRETS.md); registers the invoked services for /health reporting.
+validateIntegrationEnv(invokedServices);
+
+const PORT = env.PORT || 3030;
+
+async function start(): Promise<void> {
+  // W4 tenant credential store: with a master key configured, stored
+  // credentials (Firestore rows, AES-256-GCM) layer over the env —
+  // store → env → unconfigured — and go live on change without restart.
+  if (process.env.ALMADAR_CREDENTIAL_MASTER_KEY) {
+    try {
+      await installTenantCredentialStore(new FirestoreCredentialPersistence());
+      logger.info('Tenant credential store installed');
+    } catch (e) {
+      const message = e instanceof Error ? e.message : String(e);
+      // A configured master key IS the deployment's statement that the store
+      // is in use — failing to serve it in production is a boot failure.
+      if (env.NODE_ENV === 'production') {
+        logger.error(`Tenant credential store failed to initialize — refusing to start: ${message}`);
+        throw e;
+      }
+      logger.warn(`Tenant credential store unavailable — falling back to env credentials: ${message}`);
+    }
+  }
+
+  // Seed mock data when USE_MOCK_DATA is enabled
+  if (env.USE_MOCK_DATA) {
+    try {
+      const { initializeMockData } = await import(/* @vite-ignore */ './seedMockData.js' as string);
+      await initializeMockData();
+    } catch {
+      logger.warn('seedMockData.ts not found - skipping mock data seeding');
+    }
+  }
+
+  serve({ fetch: app.fetch, port: PORT }, () => {
+    logger.info(`Server running on port ${PORT}`);
+  });
+}
+
+start();

package/shells/almadar-shell-hono/packages/server/src/routes.ts

@@ -0,0 +1,12 @@
+/**
+ * Route Registration
+ *
+ * Compiler generates route registration code here.
+ */
+
+import type { Hono } from 'hono';
+import type { AppEnv } from '@almadar/server-hono';
+
+export function registerRoutes(_app: Hono<AppEnv>): void {
+  // {{GENERATED_ROUTE_REGISTRATION}}
+}

package/shells/almadar-shell-hono/packages/server/src/serve.ts

@@ -0,0 +1,47 @@
+/**
+ * Bun-native server entry point for `orb serve`
+ *
+ * Serves both the Hono API and the built client static files.
+ * No @hono/node-server needed: Bun serves Hono natively.
+ *
+ * @packageDocumentation
+ */
+
+import { env, logger } from '@almadar/server-hono';
+import { app } from './app.js';
+import { serveStatic } from 'hono/bun';
+import { join } from 'path';
+
+const PORT = Number(env.PORT) || 3030;
+const clientDist = join(import.meta.dir, '../../client/dist');
+
+// Seed mock data. Gated on USE_MOCK_DATA alone, matching the three other server
+// entry points — "not production" is a different question from "is the data
+// source mock", and conflating them seeds a store nothing reads.
+if (env.USE_MOCK_DATA) {
+  try {
+    const { initializeMockData } = await import(/* @vite-ignore */ './seedMockData.js' as string);
+    await initializeMockData();
+  } catch {
+    logger.warn('seedMockData.ts not found - skipping mock data seeding');
+  }
+}
+
+// Serve built client static files
+app.use('/*', serveStatic({ root: clientDist }));
+
+// SPA fallback: serve index.html for client-side routes
+app.get('*', async (c) => {
+  const file = Bun.file(join(clientDist, 'index.html'));
+  if (await file.exists()) {
+    return c.html(await file.text());
+  }
+  return c.json({ error: 'Client not built' }, 404);
+});
+
+logger.info(`Server running on http://localhost:${PORT}`);
+
+export default {
+  fetch: app.fetch,
+  port: PORT,
+};

package/shells/almadar-shell-hono/packages/server/src/services/clients.ts

@@ -0,0 +1,17 @@
+/**
+ * Service Clients — placeholder
+ *
+ * Compiler generates the real service clients here (delegating to
+ * @almadar/integrations; see orbital-shell-typescript codegen/service.rs).
+ * This stub only lets the template build standalone; an emitted app
+ * overwrites it wholesale.
+ */
+
+export const declaredServices = [] as const;
+
+export const invokedServices = [] as const;
+
+/** Overwritten at emit time with the RuntimeIntegrationManager-backed store install. */
+export async function installTenantCredentialStore(_adapter: object): Promise<void> {
+  // {{GENERATED_SERVICE_CLIENTS}}
+}

package/shells/almadar-shell-hono/packages/server/src/sse.ts

@@ -0,0 +1,20 @@
+/**
+ * Live-push SSE channel — placeholder
+ *
+ * Compiler generates the real SSE module here (connection registry +
+ * cross-client broadcast; see orbital-shell-typescript backend/server/sse.rs).
+ * This stub only lets the template build standalone; an emitted app
+ * overwrites it wholesale.
+ */
+
+export interface BusBroadcastItem {
+  type: 'bus';
+  event: string;
+  payload?: object;
+  source: { orbital: string; trait: string };
+  timestamp: number;
+}
+
+export function broadcastBusEvent(_originClientId: string | undefined, _item: BusBroadcastItem): void {
+  // {{GENERATED_SSE_BROADCAST}}
+}

package/shells/almadar-shell-hono/packages/server/tsconfig.json

@@ -0,0 +1,22 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "outDir": "./dist",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "declaration": true,
+    "declarationMap": true,
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["./src/*"],
+      "@app/shared": ["../shared/src/index.ts"],
+      "@app/shared/*": ["../shared/src/*"]
+    }
+  },
+  "include": ["src"],
+  "exclude": ["node_modules", "dist", "src/**/__tests__/**", "src/**/*.test.ts", "src/**/*.spec.ts"]
+}

package/shells/almadar-shell-hono/packages/shared/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@almadar/shell-hono-shared",
+  "version": "1.0.0",
+  "private": true,
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch"
+  },
+  "dependencies": {
+    "zod": "^3.22.0"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.7.0"
+  }
+}