@db3.ai/app 0.1.0-beta.1

package/src/server/README.md

@@ -0,0 +1,219 @@
+# Server
+
+`@db3.ai/app/server` provides the framework application service hub, the
+active-application accessor used by framework code, and isolated request-scoped
+state. Despite the module name, it does not create or own an HTTP server. A
+Fastify, Express, CLI, worker, or test runtime creates an `App` and integrates
+its own process boundary.
+
+## Module Ownership
+
+Server is the framework composition root inside `packages/app`:
+
+```text
+server/
+	App.ts
+	appContext.ts
+	RequestContext.ts
+	tests/
+	index.ts
+	README.md
+```
+
+`App` composes framework services but leaves their behavior in the owning
+service modules. It currently discovers database, auth, request context, cache,
+events, logging, URL, queue, scheduler, security, serialization, storage, and
+media services. Application-specific capabilities belong on an application
+subclass and can reuse `service(...)` for lazy singleton ownership.
+
+## Public API
+
+Import the application boundary from its supported subpath:
+
+```ts
+import { App, app, clearActiveApp, RequestContext, type AppOptions } from '@db3.ai/app/server';
+```
+
+The public surface includes:
+
+- `App` and `AppOptions` for framework service composition and lifecycle.
+- `app<TApp>()` for resolving the active application from models, jobs, and
+  other code running inside a bootstrapped process.
+- `setActiveApp(...)` and `clearActiveApp(...)` for explicit runtime and test
+  ownership.
+- `activeAppDatabase()` and `activeAppRequestContext()`, which expose optional
+  low-level context to framework internals.
+- `RequestContext` and `RequestContextValues` for request-isolated values.
+
+Normal application code should use `app().db`, `app().queue`, and the other
+service getters. `activeAppDatabase()` is a framework escape hatch, not a
+second application data-access pattern.
+
+## Application Setup
+
+Create one application during process boot and close it during shutdown:
+
+```ts
+import { App } from '@db3.ai/app/server';
+
+const application = new App({
+	config: {
+		cache: {
+			default: 'memory',
+		},
+	},
+	url: {
+		baseUrl: 'https://example.com',
+	},
+});
+
+process.once('SIGTERM', async () => {
+	await application.close();
+});
+```
+
+Constructing `App` registers it as the process's active application. Service
+getters instantiate their service on first access and return the same instance
+thereafter.
+
+`AppOptions` accepts explicit database, database behavior, auth, config,
+logging, URL, queue, serializer, and storage configuration. Cache, media, and
+security read their named options from the application config repository. When
+`config.security` exists, construction resolves the security service
+immediately so invalid key configuration fails during boot rather than on the
+first encrypted operation.
+
+The default database connection is owned by the framework and is closed by
+`App.close()`. An injected `db` connection remains owned by its caller and is
+not destroyed during application shutdown.
+
+## Extending The Service Hub
+
+An application can expose domain services without adding them to the reusable
+framework root:
+
+```ts
+import { App as FrameworkApp } from '@db3.ai/app/server';
+import { createMailFromEnv, type Mail } from '@db3.ai/app/mail';
+
+export class Application extends FrameworkApp {
+	/**
+	 * Returns the application-owned outbound mail service.
+	 *
+	 * @returns Shared mail service configured from the process environment.
+	 */
+	get mail(): Mail {
+		return this.service('mail', () => createMailFromEnv());
+	}
+}
+```
+
+Use a stable, application-owned service name. `set(name, instance)` replaces or
+registers a concrete service, which is useful for runtime adapters and tests.
+`service(name, factory)` only invokes its factory when no truthy instance has
+already been stored.
+
+## Active Application Context
+
+Framework models and queued jobs can resolve the current service hub without
+threading an `App` argument through every API:
+
+```ts
+import { app } from '@db3.ai/app/server';
+
+await app().queue.dispatch(new GenerateReportJob({ reportId }));
+```
+
+The active application is process-global. Constructing or explicitly setting a
+second application replaces the prior active reference, so runtimes should not
+interleave multiple application instances in one process. Tests must close or
+clear applications they create to prevent state leaking into another test.
+
+`clearActiveApp(application)` only clears the context when that application is
+still active. Calling it without an argument unconditionally clears the active
+reference.
+
+## Request Context
+
+`RequestContext` uses Node `AsyncLocalStorage` to isolate values across
+concurrent asynchronous request chains. An HTTP adapter should wrap the complete
+request lifecycle:
+
+```ts
+return application.requestContext.run(async () => {
+	application.requestContext.set('requestId', request.id);
+
+	return handleRequest(request);
+});
+```
+
+Use `get`, `has`, `set`, and `delete` for explicit values. `remember(...)`
+computes a value once per active request and shares an in-flight promise with
+concurrent consumers in that request:
+
+```ts
+const user = application.requestContext.remember('auth.user', async () => {
+	return authenticateRequest(request);
+});
+```
+
+A rejected remembered promise removes itself from the request store, allowing a
+later call to retry. Outside an active request, `remember(...)` invokes its
+factory normally without caching, while `set(...)` throws because there is no
+request-owned store.
+
+## Shutdown And Failure Behaviour
+
+`App.close()` clears the active reference when it owns it, detaches the Scheduler recorder,
+clears Events listeners, awaits Cache and Log shutdown, closes the
+framework-owned default database, and clears cached service instances.
+Application subclasses remain responsible for closing any additional resources
+they introduce.
+
+It does not stop a `SchedulerWorker`, drain Queue workers, or close a Redis
+queue driver. Stop accepting work, finish or deliberately terminate workers,
+and close their owned transports before closing the App, while running jobs
+can still resolve `app()`. An injected database remains caller-owned.
+
+Calling `app()` before boot fails with `No active application has been
+created.`. Invalid `DB_SYNC_COLUMNS` values also fail explicitly; accepted true
+values are `1`, `true`, `yes`, and `on`, while false values are `0`, `false`,
+`no`, and `off`. When unset, automatic safe column synchronization remains
+enabled unless `dbOptions.syncColumns` overrides it.
+
+The application hub is not an HTTP dependency container, request router, or
+durable registry. Process startup remains responsible for constructing the app,
+registering models, jobs and adapters, and attaching clean shutdown handlers.
+
+## Testing And Verification
+
+The shipped [application factory](./examples/createFirstServer.ts) and
+[process entry point](./examples/startFirstServer.ts) form the independent
+first-app walkthrough. After installing the package, Fastify, `tsx`, TypeScript
+and Vitest, copy `src/server/examples` into an application's `examples`
+directory and run `npx tsx examples/startFirstServer.ts`.
+The website includes the exact consumer-copyable HTTP injection test.
+
+
+The service-owned tests cover active-app lookup and request-context isolation,
+memoization, promise sharing, rejection recovery, and behaviour outside a
+request:
+
+```sh
+npm run test:service --workspace packages/app -- server
+```
+
+Run the complete framework suite and source checks before publishing a change:
+
+```sh
+npm test --workspace packages/app
+npm run check --workspace packages/app
+```
+
+Tests that create an `App` must use a disposable test database or inject the
+specific real framework component they need, then call `close()` or
+`clearActiveApp()` during cleanup. Relevant implementation lives in
+[`App.ts`](./App.ts), [`appContext.ts`](./appContext.ts),
+and [`RequestContext.ts`](./RequestContext.ts). Behavioural tests live at
+`packages/app/src/server/tests/` in the source repository and are not included
+in the installed runtime package.

package/src/server/RequestContext.ts

@@ -0,0 +1,122 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+
+export type RequestContextValues =
+	| Map<string, unknown>
+	| Record<string, unknown>
+	| Iterable<readonly [string, unknown]>;
+
+/**
+ * Request-scoped key/value context.
+ *
+ * Values are isolated with AsyncLocalStorage so the app singleton can expose
+ * request data without sharing it across concurrent requests.
+ */
+export class RequestContext {
+	private readonly storage = new AsyncLocalStorage<Map<string, unknown>>();
+
+	/**
+	 * Returns true when code is running inside a request context.
+	 */
+	get active(): boolean {
+		return Boolean(this.storage.getStore());
+	}
+
+	/**
+	 * Runs a callback inside an isolated request context.
+	 */
+	run<TResult>(
+		callback: () => TResult,
+		initialValues?: RequestContextValues,
+	): TResult {
+		return this.storage.run(this.initialStore(initialValues), callback);
+	}
+
+	/**
+	 * Reads a value from the active request context.
+	 */
+	get<TValue = unknown>(key: string): TValue | undefined {
+		return this.storage.getStore()?.get(key) as TValue | undefined;
+	}
+
+	/**
+	 * Returns true when the active request context contains a value for the key.
+	 */
+	has(key: string): boolean {
+		return this.storage.getStore()?.has(key) ?? false;
+	}
+
+	/**
+	 * Stores a value on the active request context.
+	 */
+	set<TValue>(key: string, value: TValue): TValue {
+		const store = this.storage.getStore();
+
+		if (!store) {
+			throw new Error('No active request context.');
+		}
+
+		store.set(key, value);
+		return value;
+	}
+
+	/**
+	 * Returns an existing request value or stores the factory result for reuse.
+	 */
+	remember<TValue>(key: string, factory: () => TValue): TValue {
+		const store = this.storage.getStore();
+
+		if (!store) {
+			return factory();
+		}
+
+		if (store.has(key)) {
+			return store.get(key) as TValue;
+		}
+
+		const value = factory();
+
+		store.set(key, value);
+
+		if (isPromiseLike(value)) {
+			Promise.resolve(value).catch(() => {
+				if (store.get(key) === value) {
+					store.delete(key);
+				}
+			});
+		}
+
+		return value;
+	}
+
+	/**
+	 * Deletes a value from the active request context.
+	 */
+	delete(key: string): boolean {
+		return this.storage.getStore()?.delete(key) ?? false;
+	}
+
+	/**
+	 * Normalises initial request values into the internal map store.
+	 */
+	private initialStore(initialValues?: RequestContextValues): Map<string, unknown> {
+		if (!initialValues) return new Map();
+		if (initialValues instanceof Map) return new Map(initialValues);
+		if (Symbol.iterator in Object(initialValues)) {
+			return new Map(initialValues as Iterable<readonly [string, unknown]>);
+		}
+
+		return new Map(Object.entries(initialValues));
+	}
+}
+
+/**
+ * Detects promise-like values without forcing callers to return real promises.
+ */
+function isPromiseLike(value: unknown): value is PromiseLike<unknown> {
+	return Boolean(
+		value
+			&& typeof value === 'object'
+			&& 'then' in value
+			&& typeof value.then === 'function',
+	);
+}

package/src/server/appContext.ts

@@ -0,0 +1,59 @@
+import type { Knex } from 'knex';
+import type { App } from './App';
+import type { RequestContext } from './RequestContext';
+
+export interface AppDatabaseProvider {
+	db: {
+		knex: Knex;
+	};
+	requestContext?: RequestContext;
+}
+
+let activeApp: AppDatabaseProvider | null = null;
+
+/**
+ * Registers the active app for framework services that need app-scoped access.
+ */
+export function setActiveApp(app: AppDatabaseProvider): AppDatabaseProvider {
+	activeApp = app;
+	return app;
+}
+
+/**
+ * Returns the active application service hub.
+ *
+ * Framework and application jobs use this accessor to resolve services when
+ * their handle methods run inside a bootstrapped worker process.
+ *
+ * @returns Active application instance.
+ */
+export function app<TApp extends AppDatabaseProvider = App>(): TApp {
+	if (!activeApp) {
+		throw new Error('No active application has been created.');
+	}
+
+	return activeApp as TApp;
+}
+
+/**
+ * Clears the active app when the caller owns the current active instance.
+ */
+export function clearActiveApp(app?: AppDatabaseProvider): void {
+	if (app && activeApp !== app) return;
+
+	activeApp = null;
+}
+
+/**
+ * Returns the active app database connection when an app is registered.
+ */
+export function activeAppDatabase(): Knex | null {
+	return activeApp?.db.knex ?? null;
+}
+
+/**
+ * Returns the active app request context when an app is registered.
+ */
+export function activeAppRequestContext(): RequestContext | null {
+	return activeApp?.requestContext ?? null;
+}

package/src/server/examples/createFirstServer.ts

@@ -0,0 +1,25 @@
+import Fastify, { type FastifyInstance } from 'fastify';
+import { App } from '@db3.ai/app/server';
+
+/**
+ * Creates a small HTTP application without opening a port or database.
+ *
+ * The caller owns listen/close, so the same app can serve requests in a process
+ * or be exercised through Fastify.inject in an isolated test.
+ *
+ * @param greeting - Application-owned greeting, configurable at process boot.
+ * @returns HTTP server with framework cleanup attached to its close lifecycle.
+ */
+export function createFirstServer(greeting = 'Hello'): FastifyInstance {
+	const application = new App({ config: { greeting } });
+	const server = Fastify();
+	server.addHook('onClose', async () => { await application.close(); });
+	server.get('/health', async () => ({ status: 'ready' }));
+	server.get<{ Params: { name: string } }>('/hello/:name', {
+		schema: { params: { type: 'object', required: ['name'], properties: { name: { type: 'string', minLength: 1, maxLength: 80 } } } },
+	}, async request => application.requestContext.run(async () => {
+		application.requestContext.set('requestId', request.id);
+		return { message: `${application.config.get<string>('greeting')}, ${request.params.name}!` };
+	}));
+	return server;
+}

package/src/server/examples/startFirstServer.ts

@@ -0,0 +1,19 @@
+import { createFirstServer } from './createFirstServer';
+
+const port = Number(process.env.PORT ?? 3000);
+if (!Number.isInteger(port) || port < 1 || port > 65535) throw new Error('PORT must be an integer from 1 to 65535.');
+const server = createFirstServer(process.env.GREETING ?? 'Hello');
+
+/** Closes the listener and framework resources when the local process stops. */
+async function shutdown(): Promise<void> {
+	await server.close();
+}
+
+process.once('SIGINT', shutdown);
+process.once('SIGTERM', shutdown);
+try {
+	console.log(await server.listen({ port, host: '127.0.0.1' }));
+} catch (error) {
+	await server.close();
+	throw error;
+}

package/src/server/index.ts

@@ -0,0 +1,16 @@
+export {
+	App,
+	type AppOptions,
+} from './App';
+export {
+	app,
+	activeAppDatabase,
+	activeAppRequestContext,
+	clearActiveApp,
+	setActiveApp,
+	type AppDatabaseProvider,
+} from './appContext';
+export {
+	RequestContext,
+	type RequestContextValues,
+} from './RequestContext';

package/src/ssr/README.md

@@ -0,0 +1,158 @@
+# Server-side rendering
+
+## Runnable public-page boundary
+
+Install `fastify@5`, copy the package's `src/ssr/examples/` into `examples/`,
+then run `npx tsx examples/runPublicPages.ts`. The injectable server renders
+isolated requests, safely embeds JSON state, preserves literal replacement-token
+text, rejects unknown API routes and recovers after a private render failure.
+It needs no SQL, listening port, Vue build or provider credentials. The exact
+consumer test is `tests/examples/runPublicPages.test.ts`. It proves the adapter
+boundary, not a complete Vue hydration or production proxy configuration.
+
+Document substitution treats rendered values literally, including `$&` and
+marker-like text in application output. Body markup still must be trusted;
+literal insertion is not HTML sanitization.
+
+`@db3.ai/app/ssr` provides the transport-neutral boundary for rendering public
+HTML. It deliberately does not live on `App`: SSR is an optional web delivery
+concern, while queues, schedulers, APIs and other processes can continue using
+the framework without Vue, Vite or Fastify SSR dependencies.
+
+The initial framework component owns:
+
+- one isolated render context per request;
+- document head and render-result contracts;
+- safe JSON hydration-state serialization;
+- deterministic HTML document assembly;
+- an optional Fastify adapter with its own error boundary;
+- a first-class Vite/Fastify lifecycle adapter for development and production.
+
+The host application owns its Vue app, router, page data loading, client and
+server entries. The optional Vite adapter owns development middleware,
+production bundle loading, manifest links, and static asset registration. SSR
+data should still be loaded through the application's HTTP API rather than
+importing app models into the frontend server entry.
+
+## Document template
+
+The application marker is required. Head and state markers are optional for
+documents that intentionally do not hydrate in the browser.
+
+```html
+<!doctype html>
+<html lang="en">
+	<head>
+		<meta charset="UTF-8">
+		<!--platform-ssr-head-->
+	</head>
+	<body>
+		<div id="app"><!--platform-ssr-app--></div>
+		<script id="__PLATFORM_SSR_STATE__" type="application/json"><!--platform-ssr-state--></script>
+		<script type="module" src="/src/entry-client.ts"></script>
+	</body>
+</html>
+```
+
+The state marker receives escaped JSON, not executable JavaScript. The client
+entry can parse it before hydrating:
+
+```ts
+const element = document.querySelector('#__PLATFORM_SSR_STATE__');
+const state = JSON.parse(element?.textContent || '{}');
+```
+
+## Fastify adapter
+
+Install Fastify in the host application and register the optional adapter:
+
+```ts
+import Fastify from 'fastify';
+import { fastifySsr } from '@db3.ai/app/ssr/fastify';
+import template from './index.html?raw';
+import { renderPage } from './src/entry-server';
+
+const server = Fastify();
+
+server.get('/api/health', async () => ({ ok: true }));
+
+await server.register(fastifySsr({
+	template,
+	render: renderPage,
+	routes: ['/blog', '/blog/*'],
+	shouldRender: (request) => {
+		const path = request.url.split('?')[0];
+		return path !== '/api' && !path.startsWith('/api/');
+	},
+}));
+```
+
+Prefer explicit `routes` when SSR owns a contained public surface. When omitted,
+the adapter retains its `/*` fallback for applications whose complete page
+surface is server rendered. Fastify's specific routes take precedence over that
+fallback. `shouldRender` remains an additional guard for reserved route prefixes
+so an unknown API route does not accidentally receive an HTML page.
+
+The application renderer returns markup and can collect status, head metadata
+and hydration state on its request-owned context:
+
+```ts
+import type { SsrRenderer } from '@db3.ai/app/ssr';
+
+export const renderPage: SsrRenderer = async (context) => {
+	context.head.title = 'Example App';
+	context.state.page = await loadPageThroughHttpApi(context.request.url);
+
+	return {
+		appHtml: renderApplicationMarkup(context.state.page),
+	};
+};
+```
+
+Create a fresh Vue application, router and store inside every call to the
+renderer. Module-level mutable auth, router or store state can leak between
+concurrent requests and must not be used.
+
+## Vite and Fastify integration
+
+`@db3.ai/app/ssr/vite` provides the complete Vite lifecycle while retaining
+explicit route ownership:
+
+```ts
+import Fastify from 'fastify';
+import { fastifyViteSsr } from '@db3.ai/app/ssr/vite';
+
+const server = Fastify();
+
+await server.register(fastifyViteSsr({
+	root: import.meta.dirname,
+	routes: ['/blog', '/blog/*'],
+	viteConfigFile: 'vite.marketing.config.ts',
+	template: 'marketing.html',
+	developmentEntry: '/src/marketing/entry-server.ts',
+	preloadJavaScript: false,
+	staticAssets: {
+		prefix: '/site-assets/',
+		directory: 'dist/client/site-assets',
+	},
+}));
+```
+
+`viteConfigFile` lets one application keep its SPA and SSR marketing graphs
+separate while sharing the same source tree. The SSR adapter uses that config
+for development transforms; production continues loading the explicit client
+and server output paths supplied by the application.
+
+In development the adapter uses Vite middleware mode, transforms the HTML shell
+per request, hot-loads `/src/entry-server.ts`, and makes Vite's source, module,
+dependency, filesystem, and HMR URL namespaces available to the browser. Unknown
+page URLs still fall through to the application's ordinary not-found boundary.
+In production it reads `dist/client/index.html`, imports
+`dist/server/entry-server.js`, serves the configured asset directory, and maps
+`context.modules` through Vite's SSR manifest. Set `preloadJavaScript: false`
+for HTML/CSS-only pages; hydrating apps can retain the default module-preload
+behavior.
+
+This makes SSR designation deliberate and visible: a page is server-rendered
+only when the application router implements it and its URL appears in the
+adapter's `routes` list. An existing SPA can continue owning every other route.

package/src/ssr/constants.ts

@@ -0,0 +1,8 @@
+/** Marker replaced with document head tags during SSR document assembly. */
+export const SSR_HEAD_MARKER = '<!--platform-ssr-head-->';
+
+/** Marker replaced with application markup during SSR document assembly. */
+export const SSR_APP_MARKER = '<!--platform-ssr-app-->';
+
+/** Marker replaced with safely serialised hydration state. */
+export const SSR_STATE_MARKER = '<!--platform-ssr-state-->';

package/src/ssr/contracts/DocumentHead.ts

@@ -0,0 +1,35 @@
+/** Attribute value supported by server-rendered document head tags. */
+export type DocumentHeadAttributeValue = string | number | boolean | null | undefined;
+
+/** Attributes written onto a server-rendered document head tag. */
+export type DocumentHeadAttributes = Record<string, DocumentHeadAttributeValue>;
+
+/**
+ * Script emitted through the single server-rendered document head pipeline.
+ *
+ * Content must come from trusted application code. The renderer prevents a
+ * closing script sequence from escaping the tag but does not sanitise scripts.
+ */
+export interface DocumentHeadScript {
+	/** HTML attributes written onto the script element. */
+	attributes?: DocumentHeadAttributes;
+	/** Trusted inline script or JSON-LD content. */
+	content?: string;
+}
+
+/**
+ * Head metadata collected while rendering one HTTP request.
+ *
+ * Applications can mutate this request-owned object from their SSR router or
+ * page components. It is rendered once into the document template.
+ */
+export interface DocumentHead {
+	/** Browser and search-result title for the rendered document. */
+	title?: string;
+	/** Meta elements, including descriptions, robots and social metadata. */
+	meta: DocumentHeadAttributes[];
+	/** Link elements, including canonical URLs and alternate resources. */
+	link: DocumentHeadAttributes[];
+	/** Trusted scripts, including JSON-LD structured data. */
+	script: DocumentHeadScript[];
+}

package/src/ssr/contracts/SsrRenderContext.ts

@@ -0,0 +1,25 @@
+import type { DocumentHead } from './DocumentHead';
+import type { SsrRequest } from './SsrRequest';
+
+/** JSON-compatible request state made available to the hydrating client. */
+export type SsrState = Record<string, unknown>;
+
+/**
+ * Mutable state isolated to one server-side render request.
+ *
+ * Vue and other renderers may use `modules` to record the modules touched by a
+ * render. A later build adapter can map those identifiers to route-specific
+ * JavaScript and CSS without changing the application renderer contract.
+ */
+export interface SsrRenderContext<TState extends object = SsrState> {
+	/** Transport-neutral request information. */
+	request: SsrRequest;
+	/** Response status used when the render result does not override it. */
+	status: number;
+	/** Document metadata collected during rendering. */
+	head: DocumentHead;
+	/** State serialised into the document for client hydration. */
+	state: TState;
+	/** Module identifiers observed by the concrete server renderer. */
+	modules: Set<string>;
+}