@db3.ai/app 0.1.0-beta.1 → 0.1.0

package/dist/apps/commands/disableApp.js

@@ -0,0 +1,5 @@
+import { app } from '../../server/index.js';
+/** Disables an app without deleting its data. */
+export async function disableApp(id) {
+    return app().apps.disable(id);
+}

package/dist/apps/commands/enableApp.d.ts

@@ -0,0 +1,2 @@
+/** Enables an installed app for the next runtime boot. */
+export declare function enableApp(id: string): Promise<import("../index.js").AppDescription>;

package/dist/apps/commands/enableApp.js

@@ -0,0 +1,5 @@
+import { app } from '../../server/index.js';
+/** Enables an installed app for the next runtime boot. */
+export async function enableApp(id) {
+    return app().apps.enable(id);
+}

package/dist/apps/commands/index.d.ts

@@ -0,0 +1,10 @@
+import { listApps } from './listApps.js';
+import { installApp } from './installApp.js';
+import { enableApp } from './enableApp.js';
+import { disableApp } from './disableApp.js';
+import { uninstallApp } from './uninstallApp.js';
+import { rollbackApp } from './rollbackApp.js';
+import { makeAppMigration } from './makeAppMigration.js';
+export { listApps, installApp, enableApp, disableApp, uninstallApp, makeAppMigration, rollbackApp };
+/** CLI adapters for the same app-management operations used by programmatic and visual clients. */
+export declare const appsCommands: import("../../cli/index.js").CliCommand[];

package/dist/apps/commands/index.js

@@ -0,0 +1,27 @@
+import { defineCommand } from '../../cli/index.js';
+import { listApps } from './listApps.js';
+import { installApp } from './installApp.js';
+import { enableApp } from './enableApp.js';
+import { disableApp } from './disableApp.js';
+import { uninstallApp } from './uninstallApp.js';
+import { rollbackApp } from './rollbackApp.js';
+import { makeAppMigration } from './makeAppMigration.js';
+export { listApps, installApp, enableApp, disableApp, uninstallApp, makeAppMigration, rollbackApp };
+/** CLI adapters for the same app-management operations used by programmatic and visual clients. */
+export const appsCommands = [
+    defineCommand({ name: 'apps:list', description: 'Inspect app definitions and installation state.', handle: listApps }),
+    defineCommand({
+        name: 'apps:make-migration', description: 'Generate a local app migration without changing the database.',
+        parameters: [{ name: 'id', required: true }, { name: 'name', required: false }],
+        /** Delegates development source generation to the app-owned migration manager. */
+        handle: parameters => makeAppMigration(parameters.id, parameters.name),
+    }),
+    ...[
+        ['install', installApp], ['enable', enableApp], ['disable', disableApp], ['uninstall', uninstallApp], ['rollback', rollbackApp],
+    ].map(([action, operation]) => defineCommand({
+        name: `apps:${action}`, description: `${action} a registered app in a stopped maintenance process.`,
+        parameters: [{ name: 'id', required: true }],
+        /** Maps CLI input to the normal service action. */
+        handle: parameters => operation(parameters.id),
+    })),
+];

package/dist/apps/commands/installApp.d.ts

@@ -0,0 +1,2 @@
+/** Installs or upgrades one registered app in a stopped maintenance process. */
+export declare function installApp(id: string): Promise<import("../index.js").AppDescription>;

package/dist/apps/commands/installApp.js

@@ -0,0 +1,5 @@
+import { app } from '../../server/index.js';
+/** Installs or upgrades one registered app in a stopped maintenance process. */
+export async function installApp(id) {
+    return app().apps.install(id);
+}

package/dist/apps/commands/listApps.d.ts

@@ -0,0 +1,2 @@
+/** Lists source definitions and retained installations for CLI or visual clients. */
+export declare function listApps(): Promise<import("../index.js").AppDescription[]>;

package/dist/apps/commands/listApps.js

@@ -0,0 +1,5 @@
+import { app } from '../../server/index.js';
+/** Lists source definitions and retained installations for CLI or visual clients. */
+export async function listApps() {
+    return app().apps.describe();
+}

package/dist/apps/commands/makeAppMigration.d.ts

@@ -0,0 +1,2 @@
+/** Generates a frozen app-owned migration and snapshot in development, without applying DDL. */
+export declare function makeAppMigration(id: string, name?: string): Promise<import("../../db/index.js").MakeMigrationResult>;

package/dist/apps/commands/makeAppMigration.js

@@ -0,0 +1,9 @@
+import { app } from '../../server/index.js';
+/** Generates a frozen app-owned migration and snapshot in development, without applying DDL. */
+export async function makeAppMigration(id, name) {
+    await app().apps.load(id);
+    const manager = app().apps.migrations(id);
+    if (!manager)
+        throw new Error(`App "${id}" has no database definition.`);
+    return manager.makeMigration({ name });
+}

package/dist/apps/commands/rollbackApp.d.ts

@@ -0,0 +1,2 @@
+/** Runs the latest app-owned down migration in a stopped process; disable the app first. */
+export declare function rollbackApp(id: string): Promise<import("../../db/index.js").RollbackResult>;

package/dist/apps/commands/rollbackApp.js

@@ -0,0 +1,5 @@
+import { app } from '../../server/index.js';
+/** Runs the latest app-owned down migration in a stopped process; disable the app first. */
+export async function rollbackApp(id) {
+    return app().apps.rollback(id);
+}

package/dist/apps/commands/uninstallApp.d.ts

@@ -0,0 +1,2 @@
+/** Deregisters an app installation while preserving its tables and history. */
+export declare function uninstallApp(id: string): Promise<import("../index.js").AppDescription>;

package/dist/apps/commands/uninstallApp.js

@@ -0,0 +1,5 @@
+import { app } from '../../server/index.js';
+/** Deregisters an app installation while preserving its tables and history. */
+export async function uninstallApp(id) {
+    return app().apps.uninstall(id);
+}

package/dist/apps/contracts/AppAction.d.ts

@@ -0,0 +1,2 @@
+/** Lifecycle actions supported by a host that explicitly opts into single-process management. */
+export type AppAction = 'install' | 'enable' | 'disable' | 'uninstall';

package/dist/apps/contracts/AppAction.js

@@ -0,0 +1 @@
+export {};

package/dist/apps/contracts/AppDefinition.d.ts

@@ -0,0 +1,45 @@
+import type { App } from '../../server/App.js';
+import type { ActiveRecordClass } from '../../db/index.js';
+import type { AppManifest } from './AppManifest.js';
+import type { AppRoute } from './AppRoute.js';
+import type { QueueableJobClass } from '../../queue/index.js';
+import type { Schedule } from '../../scheduler/index.js';
+import type { AppNavigation } from './AppNavigation.js';
+import type { AppNavigationContext } from './AppNavigationContext.js';
+/** Explicit contributions of one local or npm-distributed app. Importing it has no runtime effects. */
+export interface AppDefinition<TService = unknown> {
+    manifest: AppManifest;
+    /** Creates one public service in the host runtime; never create a second framework App. */
+    create(host: App): TService;
+    /** App-owned models and immutable migration assets, resolved relative to the defining module. */
+    database?: {
+        models: readonly ActiveRecordClass[];
+        /** Directory containing migrations/ and schema.snapshot.json, in source or a published package. */
+        directory: URL;
+    };
+    /** Retry-safe app-owned setup after migrations have succeeded. */
+    afterInstall?(host: App): void | Promise<void>;
+    routes?: readonly AppRoute<TService>[];
+    /** Serializable job classes with explicit names beneath this app's id, such as social.review. */
+    jobs?: readonly QueueableJobClass[];
+    /** Synchronously declares recurring work for the enabled app during each process boot. */
+    schedule?(schedule: Schedule, service: TService): void;
+    /** Computes viewer-specific navigation. Undefined uses manifest links; null hides the app. */
+    navigation?(context: AppNavigationContext, service: TService): AppNavigation | null | undefined | Promise<AppNavigation | null | undefined>;
+    /** Starts resources after dependency services exist. Use defer immediately for failure-safe cleanup. */
+    start?(context: AppStartContext<TService>): void | Promise<void>;
+    /** Checks app-specific outstanding work before uninstall; throwing leaves the installation intact. */
+    beforeUninstall?(host: App): void | Promise<void>;
+}
+/** Resource ownership during startup. Cleanup runs in reverse registration order, including on failure. */
+export interface AppStartContext<TService> {
+    host: App;
+    service: TService;
+    defer(cleanup: () => void | Promise<void>): void;
+}
+/** Explicit host composition, keyed by the matching manifest identifier. */
+export type AppDefinitions = Readonly<Record<string, AppDefinition<any>>>;
+/** Optional public service types inferred from the host's actual composition. */
+export type AppServices<TDefinitions extends AppDefinitions> = {
+    readonly [K in keyof TDefinitions]: TDefinitions[K] extends AppDefinition<infer TService> ? TService | undefined : never;
+};

package/dist/apps/contracts/AppDefinition.js

@@ -0,0 +1 @@
+export {};

package/dist/apps/contracts/AppDescription.d.ts

@@ -0,0 +1,32 @@
+import type { AppManifest } from './AppManifest.js';
+import type { ScheduledTaskDefinition } from '../../scheduler/index.js';
+/** Durable installation state. Enabled installations become available only after a successful boot. */
+export type AppInstallationState = 'enabled' | 'disabled' | 'uninstalled' | 'failed';
+/** Inspectable app structure without constructors, secrets or filesystem paths. */
+export interface AppDescription {
+    manifest: AppManifest;
+    registered: boolean;
+    state: AppInstallationState | 'available';
+    ready: boolean;
+    installedVersion: string | null;
+    models: {
+        name: string;
+        table: string;
+    }[];
+    routes: {
+        method: string;
+        path: string;
+    }[];
+    /** Stable durable job names owned by this app. */
+    jobs: string[];
+    /** Runtime declarations collected during boot; empty before the first boot. */
+    schedules: ScheduledTaskDefinition[];
+}
+/** Browser renderer contract. The host supplies its own component type and routing implementation. */
+export interface AppClientDefinition<TComponent> {
+    id: string;
+    /** Statically discoverable lazy import, allowing bundlers to keep server code out of browser assets. */
+    load(): Promise<{
+        default: TComponent;
+    }>;
+}

package/dist/apps/contracts/AppDescription.js

@@ -0,0 +1 @@
+export {};

package/dist/apps/contracts/AppManifest.d.ts

@@ -0,0 +1,30 @@
+import type { AppNavigationBadge } from './AppNavigationBadge.js';
+/** Browser-safe description of an app, shared by runtime, navigation and visual tools. */
+export interface AppManifest {
+    /** Stable lowercase identifier; also owns the database and route namespaces. */
+    id: string;
+    name: string;
+    /** Stable semantic release version, for example 1.2.0. */
+    version: string;
+    description?: string;
+    /** Plain text glyph or emoji. Render as text, never as HTML. */
+    icon?: string;
+    /** Public service contract generation, independent of package release version. */
+    apiVersion?: number;
+    /** Required app identifiers mapped to their exact public API generation. */
+    requires?: Readonly<Record<string, number>>;
+    /** Optional integrations; absent apps are allowed, incompatible installed apps are not. */
+    optional?: Readonly<Record<string, number>>;
+    /** Default destinations beneath /apps/{id}; a runtime navigation provider may replace these per viewer. */
+    navigation?: readonly AppMenuItem[];
+}
+/** One app-owned navigation item; nesting is deliberately limited to one level. */
+export interface AppMenuItem {
+    id: string;
+    label: string;
+    /** Empty string opens the app's main view; otherwise a simple relative path. */
+    path: string;
+    badge?: AppNavigationBadge;
+    /** Optional plain-text information about this destination. */
+    description?: string;
+}

package/dist/apps/contracts/AppManifest.js

@@ -0,0 +1 @@
+export {};

package/dist/apps/contracts/AppNavigation.d.ts

@@ -0,0 +1,9 @@
+import type { AppMenuItem } from './AppManifest.js';
+import type { AppNavigationBadge } from './AppNavigationBadge.js';
+/** One app's current navigation contribution. Return null from the provider to hide the app for this viewer. */
+export interface AppNavigation {
+    items: readonly AppMenuItem[];
+    badge?: AppNavigationBadge;
+    /** Short, plain-text information beneath the app's name. */
+    description?: string;
+}

package/dist/apps/contracts/AppNavigation.js

@@ -0,0 +1 @@
+export {};

package/dist/apps/contracts/AppNavigationBadge.d.ts

@@ -0,0 +1,6 @@
+/** A non-negative count with a complete accessible label, rendered as plain text by the host. */
+export interface AppNavigationBadge {
+    count: number;
+    /** For example, "3 saved opportunities". */
+    label: string;
+}

package/dist/apps/contracts/AppNavigationBadge.js

@@ -0,0 +1 @@
+export {};

package/dist/apps/contracts/AppNavigationContext.d.ts

@@ -0,0 +1,8 @@
+/** Request-scoped identity supplied by the host after authentication and scope authorization. Never store it on an app singleton. */
+export interface AppNavigationContext {
+    readonly actor: {
+        readonly id: string;
+    };
+    /** Optional organisation already authorized by the host; apps must still enforce their own data permissions. */
+    readonly organisationId?: string;
+}

package/dist/apps/contracts/AppNavigationContext.js

@@ -0,0 +1 @@
+export {};

package/dist/apps/contracts/AppNavigationResult.d.ts

@@ -0,0 +1,12 @@
+import type { AppNavigation } from './AppNavigation.js';
+/** Browser-safe contributions for one viewer. Results are request-scoped and must not be cached across users. */
+export interface AppNavigationResult {
+    /** Registry-owned identity and public metadata attached to each successful contribution. */
+    apps: Array<AppNavigation & {
+        appId: string;
+        name: string;
+        icon?: string;
+    }>;
+    /** Apps whose providers failed or returned invalid data. Their links are omitted without exposing error details. */
+    unavailable: string[];
+}

package/dist/apps/contracts/AppNavigationResult.js

@@ -0,0 +1 @@
+export {};

package/dist/apps/contracts/AppRoute.d.ts

@@ -0,0 +1,19 @@
+/** Transport-neutral authenticated request passed to an app-owned route. */
+export interface AppRouteContext<TService> {
+    service: TService;
+    /** Identity established by the host adapter; never taken from a request body. */
+    actor: {
+        id: string;
+    };
+    body: unknown;
+    params: Readonly<Record<string, string>>;
+    query: Readonly<Record<string, unknown>>;
+}
+/** One route mounted beneath /api/apps/{appId}; authorization remains mandatory in the adapter. */
+export interface AppRoute<TService = unknown> {
+    method: 'GET' | 'POST' | 'PATCH' | 'PUT' | 'DELETE';
+    path: string;
+    /** HTTP success status; defaults to 200. */
+    status?: number;
+    handle(context: AppRouteContext<TService>): unknown | Promise<unknown>;
+}

package/dist/apps/contracts/AppRoute.js

@@ -0,0 +1 @@
+export {};

package/dist/apps/contracts/DiscoveredApp.d.ts

@@ -0,0 +1,10 @@
+import type { AppManifest } from './AppManifest.js';
+/** Metadata-only discovery result; reading it does not import the app's server or browser code. */
+export interface DiscoveredApp {
+    manifest: AppManifest;
+    directory: string;
+    entry: string;
+    client?: string;
+    /** Direct npm dependency, absent for an in-project apps/{id} directory. */
+    packageName?: string;
+}

package/dist/apps/contracts/DiscoveredApp.js

@@ -0,0 +1 @@
+export {};

package/dist/apps/contracts/InstalledApps.d.ts

@@ -0,0 +1,3 @@
+/** Generated declaration merging target. Properties are optional because installation is runtime state. */
+export interface InstalledApps {
+}

package/dist/apps/contracts/InstalledApps.js

@@ -0,0 +1 @@
+export {};

package/dist/apps/contracts/index.d.ts

@@ -0,0 +1,11 @@
+export type { AppManifest, AppMenuItem } from './AppManifest.js';
+export type { AppDefinition, AppDefinitions, AppServices, AppStartContext } from './AppDefinition.js';
+export type { AppRoute, AppRouteContext } from './AppRoute.js';
+export type { AppDescription, AppInstallationState, AppClientDefinition } from './AppDescription.js';
+export type { DiscoveredApp } from './DiscoveredApp.js';
+export type { InstalledApps } from './InstalledApps.js';
+export type { AppAction } from './AppAction.js';
+export type { AppNavigation } from './AppNavigation.js';
+export type { AppNavigationBadge } from './AppNavigationBadge.js';
+export type { AppNavigationContext } from './AppNavigationContext.js';
+export type { AppNavigationResult } from './AppNavigationResult.js';

package/dist/apps/contracts/index.js

@@ -0,0 +1 @@
+export {};

package/dist/apps/defineApp.d.ts

@@ -0,0 +1,7 @@
+import type { AppDefinition } from './contracts/index.js';
+/**
+ * Defines an app without installing, connecting or registering it globally.
+ * @param definition - Public service, metadata and app-owned contributions.
+ * @returns Definition preserving the inferred public service type.
+ */
+export declare function defineApp<TService>(definition: AppDefinition<TService>): AppDefinition<TService>;

package/dist/apps/defineApp.js

@@ -0,0 +1,8 @@
+/**
+ * Defines an app without installing, connecting or registering it globally.
+ * @param definition - Public service, metadata and app-owned contributions.
+ * @returns Definition preserving the inferred public service type.
+ */
+export function defineApp(definition) {
+    return definition;
+}

package/dist/apps/discoverApps.d.ts

@@ -0,0 +1,3 @@
+import type { DiscoveredApp } from './contracts/index.js';
+/** Discovers local apps and opted-in direct npm dependencies without executing their code. */
+export declare function discoverApps(directory: string): DiscoveredApp[];

package/dist/apps/discoverApps.js

@@ -0,0 +1,62 @@
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { validateAppDefinitions } from './validateAppDefinitions.js';
+/** Discovers local apps and opted-in direct npm dependencies without executing their code. */
+export function discoverApps(directory) {
+    const found = [];
+    const root = join(directory, 'apps');
+    if (existsSync(root)) {
+        for (const item of readdirSync(root, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+            if (item.isDirectory() && existsSync(join(root, item.name, 'manifest.json')))
+                found.push(readApp(join(root, item.name), item.name));
+        }
+    }
+    const packageFile = join(directory, 'package.json');
+    if (existsSync(packageFile)) {
+        const host = JSON.parse(readFileSync(packageFile, 'utf8'));
+        const require = createRequire(packageFile);
+        for (const name of Object.keys({ ...host.dependencies, ...host.optionalDependencies }).sort()) {
+            let file;
+            try {
+                file = require.resolve(`${name}/package.json`);
+            }
+            catch {
+                continue;
+            } // Packages must export package.json to opt into metadata-only discovery.
+            const metadata = JSON.parse(readFileSync(file, 'utf8'));
+            if (metadata.db3?.app !== true)
+                continue;
+            found.push(readApp(dirname(file), basename(name), name, metadata.db3));
+        }
+    }
+    const definitions = Object.create(null);
+    for (const app of found) {
+        const id = app.manifest.id;
+        if (Object.hasOwn(definitions, id))
+            throw new Error(`Duplicate app "${id}". Keep either the local folder or the npm package.`);
+        definitions[id] = { manifest: app.manifest, create: () => undefined };
+    }
+    validateAppDefinitions(definitions, [...Object.getOwnPropertyNames(Object.prototype), 'then', 'toJSON']);
+    return found;
+}
+/** Reads one conventional root manifest and resolves entries contained in that app's directory. */
+function readApp(directory, id, packageName, entries) {
+    const manifest = JSON.parse(readFileSync(join(directory, 'manifest.json'), 'utf8'));
+    if (manifest.id !== undefined && manifest.id !== id)
+        throw new Error(`App folder "${id}" disagrees with manifest identifier "${manifest.id}".`);
+    const entry = containedEntry(directory, entries?.entry ?? 'App.ts');
+    const clientPath = entries?.client ?? 'client/index.ts';
+    const client = containedEntry(directory, clientPath);
+    return { manifest: { ...manifest, id }, directory, entry, ...(existsSync(client) ? { client } : {}), ...(packageName ? { packageName } : {}) };
+}
+/** Rejects entry paths that escape the package or local app root. */
+function containedEntry(directory, entry) {
+    if (typeof entry !== 'string' || isAbsolute(entry))
+        throw new Error('App entries must be relative paths.');
+    const target = resolve(directory, entry);
+    const path = relative(directory, target);
+    if (!path || path === '..' || path.startsWith(`..${sep}`) || isAbsolute(path))
+        throw new Error('App entries must remain inside their app directory.');
+    return target;
+}

package/dist/apps/fastify.d.ts

@@ -0,0 +1 @@
+export { registerAppRoutes } from './registerAppRoutes.js';

package/dist/apps/fastify.js

@@ -0,0 +1 @@
+export { registerAppRoutes } from './registerAppRoutes.js';

package/dist/apps/index.d.ts

@@ -0,0 +1,7 @@
+export * from './contracts/index.js';
+export { defineApp } from './defineApp.js';
+export { Apps } from './Apps.js';
+export { AppRouteError } from './AppRouteError.js';
+export { AppService } from './AppService.js';
+export { discoverApps } from './discoverApps.js';
+export { writeAppTypes } from './writeAppTypes.js';

package/dist/apps/index.js

@@ -0,0 +1,7 @@
+export * from './contracts/index.js';
+export { defineApp } from './defineApp.js';
+export { Apps } from './Apps.js';
+export { AppRouteError } from './AppRouteError.js';
+export { AppService } from './AppService.js';
+export { discoverApps } from './discoverApps.js';
+export { writeAppTypes } from './writeAppTypes.js';

package/dist/apps/normalizeAppNavigation.d.ts

@@ -0,0 +1,3 @@
+import type * as apps from './contracts/index.js';
+/** Validates a contribution and copies only supported, browser-safe fields into the response. */
+export declare function normalizeAppNavigation(value: apps.AppNavigation): apps.AppNavigation;

package/dist/apps/normalizeAppNavigation.js

@@ -0,0 +1,30 @@
+/** Validates a contribution and copies only supported, browser-safe fields into the response. */
+export function normalizeAppNavigation(value) {
+    if (!value || !Array.isArray(value.items))
+        throw new Error('Navigation must provide an items array.');
+    const ids = new Set();
+    return {
+        ...details(value),
+        items: value.items.map(item => {
+            if (!item || typeof item.id !== 'string' || !item.id.trim() || ids.has(item.id) || typeof item.label !== 'string' || !item.label.trim() || typeof item.path !== 'string' || !/^(?:[a-z0-9-]+(?:\/[a-z0-9-]+)*)?$/.test(item.path))
+                throw new Error('Invalid or duplicate navigation item.');
+            ids.add(item.id);
+            return { id: item.id, label: item.label, path: item.path, ...details(item) };
+        }),
+    };
+}
+/** Copies optional display information without passing through arbitrary provider data. */
+function details(value) {
+    const result = {};
+    if (value.description !== undefined) {
+        if (typeof value.description !== 'string')
+            throw new Error('Navigation descriptions must be plain text.');
+        result.description = value.description;
+    }
+    if (value.badge !== undefined) {
+        if (!value.badge || !Number.isSafeInteger(value.badge.count) || value.badge.count < 0 || typeof value.badge.label !== 'string' || !value.badge.label.trim())
+            throw new Error('Navigation badges require a non-negative integer count and an accessible label.');
+        result.badge = { count: value.badge.count, label: value.badge.label };
+    }
+    return result;
+}

package/dist/apps/registerAppRoutes.d.ts

@@ -0,0 +1,6 @@
+import type { FastifyInstance, FastifyRequest } from 'fastify';
+import type { Apps } from './Apps.js';
+/** Mounts dynamic app routes behind mandatory host authorization; newly installed apps become reachable immediately. */
+export declare function registerAppRoutes(server: FastifyInstance, apps: Apps<any>, authorize: (request: FastifyRequest, appId: string) => Promise<{
+    id: string;
+}>): void;

package/dist/apps/registerAppRoutes.js

@@ -0,0 +1,52 @@
+import { AppRouteError } from './AppRouteError.js';
+/** Mounts dynamic app routes behind mandatory host authorization; newly installed apps become reachable immediately. */
+export function registerAppRoutes(server, apps, authorize) {
+    for (const url of ['/api/apps/:appId', '/api/apps/:appId/*']) {
+        server.route({
+            method: ['GET', 'POST', 'PATCH', 'PUT', 'DELETE'], url,
+            /** Drains in-flight requests before lifecycle changes and passes only a verified actor to app code. */
+            handler: async (request, reply) => {
+                try {
+                    return await apps.run(async () => {
+                        const { appId, '*': suffix = '' } = request.params;
+                        const service = apps.get(appId);
+                        if (service === undefined)
+                            return reply.code(404).send({ message: 'App is unavailable.' });
+                        const candidates = apps.routes().filter(item => item.appId === appId && item.route.method === request.method).sort((a, b) => (a.route.path.match(/:/g)?.length ?? 0) - (b.route.path.match(/:/g)?.length ?? 0));
+                        for (const { route } of candidates) {
+                            const params = matchPath(route.path, `/${suffix}`);
+                            if (!params)
+                                continue;
+                            const actor = await authorize(request, appId);
+                            if (!actor?.id)
+                                throw new AppRouteError(401, 'Please sign in.');
+                            const result = await route.handle({ service, actor, body: request.body, params, query: request.query });
+                            return reply.code(route.status ?? 200).send(result);
+                        }
+                        return reply.code(404).send({ message: 'App route not found.' });
+                    });
+                }
+                catch (error) {
+                    if (error instanceof AppRouteError)
+                        return reply.code(error.statusCode).send({ message: error.message });
+                    throw error;
+                }
+            },
+        });
+    }
+}
+/** Matches validated route segments and captures named parameters without evaluating arbitrary regular expressions. */
+function matchPath(pattern, path) {
+    const expected = pattern.split('/');
+    const actual = path.split('/');
+    if (expected.length !== actual.length)
+        return;
+    const params = Object.create(null);
+    for (let index = 0; index < expected.length; index++) {
+        if (expected[index].startsWith(':') && actual[index])
+            params[expected[index].slice(1)] = actual[index];
+        else if (expected[index] !== actual[index])
+            return;
+    }
+    return params;
+}

package/dist/apps/validateAppDefinitions.d.ts

@@ -0,0 +1,3 @@
+import type * as apps from './contracts/index.js';
+/** Validates names, contribution ownership and dependency order before any app code is started. */
+export declare function validateAppDefinitions(definitions: apps.AppDefinitions, reserved: readonly string[]): string[];