@zyno-io/dk-server-foundation 26.216.430

package/src/database/migration/index.ts

@@ -0,0 +1,35 @@
+import { App } from '@deepkit/app';
+import { ClassType } from '@deepkit/core';
+import { FrameworkModule } from '@deepkit/framework';
+
+import { r } from '../../app/resolver';
+import { DBProvider } from '../../app/state';
+import { BaseDatabase } from '../common';
+import { MigrationCharactersCommand } from './characters';
+import { MigrationCreateCommand } from './create/MigrationCreateCommand';
+import { MigrationResetCommand } from './MigrationResetCommand';
+import { MigrationRunCommand } from './MigrationRunCommand';
+
+export * from './characters';
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function replaceMigrationCommands(_app: App<any>, frameworkModule: FrameworkModule, dbClass?: ClassType<BaseDatabase>) {
+    frameworkModule.controllers = frameworkModule.controllers.filter(c => !c.name.startsWith('Migration'));
+
+    if (!dbClass) {
+        return;
+    }
+
+    frameworkModule.addController(MigrationRunCommand);
+    frameworkModule.addController(MigrationCreateCommand);
+    frameworkModule.addController(MigrationCharactersCommand);
+    frameworkModule.addController(MigrationResetCommand);
+}
+
+export function createMigration<T extends BaseDatabase>(fn: (db: T) => Promise<void>) {
+    return fn;
+}
+
+export function runMigrations() {
+    return new MigrationRunCommand(r(DBProvider)).execute();
+}

package/src/database/migration/migration.entity.ts

@@ -0,0 +1,10 @@
+import { entity, PrimaryKey } from '@deepkit/type';
+
+import { BaseEntity } from '../entity';
+
+@entity.name('_migrations')
+export class MigrationEntity extends BaseEntity {
+    name!: string & PrimaryKey;
+    executedAt!: Date;
+    durationMs!: number;
+}

package/src/database/mysql.ts

@@ -0,0 +1,140 @@
+import { ClassType, getClassName } from '@deepkit/core';
+import { Logger } from '@deepkit/logger';
+import { MySQLConnection, MySQLDatabaseAdapter as BaseMySQLDatabaseAdapter } from '@deepkit/mysql';
+import { Database, DatabaseSession } from '@deepkit/orm';
+import { isNonUndefined } from '@deepkit/sql';
+import { databaseAnnotation, ReflectionKind, Type } from '@deepkit/type';
+import { PoolConfig } from 'mariadb';
+
+import { getAppConfig, r } from '../app/resolver';
+import { globalState } from '../app/state';
+import { Coordinate } from '.';
+import { BaseDatabase } from './common';
+
+export type MySQLDatabaseSession = DatabaseSession<MySQLDatabaseAdapter>;
+
+const originalRun = MySQLConnection.prototype.run;
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+MySQLConnection.prototype.run = async function (sql: string, params: any[] = []) {
+    await originalRun.call(this, sql, params);
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    return this.lastExecResult?.[0] as any;
+};
+
+export class MySQLDatabaseAdapter extends BaseMySQLDatabaseAdapter {
+    registerTransformations() {
+        // any
+        this.platform.serializer.deserializeRegistry.register(ReflectionKind.any, (_type, state) => {
+            state.addSetter(state.accessor);
+        });
+
+        // date string
+        this.platform.serializer.deserializeRegistry.addDecorator(
+            t => t.typeName === 'DateString',
+            (_type, state) => {
+                state.addSetter(`${state.accessor} instanceof Date ? ${state.accessor}.toISOString().substring(0, 10) : ${state.accessor}`);
+                state.ended = true;
+            }
+        );
+
+        // register POINT as a coordinate
+        // a specificity of 2 on the type guard allows the default object literal (at specificity 1) to match the {x,y} object
+        // while allowing a fallback to match the POINT object coming from the mariadb driver
+        const isCoordinateClass = (t: Type): boolean => t.kind === ReflectionKind.class && getClassName(t.classType) === 'Coordinate';
+        const isCoordinateTypeName = (t: Type): boolean => {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const typeName = (t as any).typeName;
+            return typeName === 'MySQLCoordinate' || typeName === 'NullableMySQLCoordinate' || typeName === 'Coordinate';
+        };
+        const hasMySQLPointAnnotation = (t: Type): boolean => {
+            const mysqlOptions = databaseAnnotation.getDatabase<{ type?: string }>(t, 'mysql');
+            return mysqlOptions?.type === 'point';
+        };
+        const containsCoordinate = (t: Type): boolean => {
+            if (isCoordinateClass(t)) return true;
+            if (isCoordinateTypeName(t)) return true;
+            if (hasMySQLPointAnnotation(t)) return true;
+            if (t.kind === ReflectionKind.intersection) return t.types.some(containsCoordinate);
+            if (t.kind === ReflectionKind.union) return t.types.filter(isNonUndefined).some(containsCoordinate);
+            return false;
+        };
+        this.platform.addType(containsCoordinate, 'point');
+        this.platform.serializer.typeGuards.registerClass(2, Coordinate, (_type, state) => {
+            state.addSetter(`typeof ${state.accessor} === 'object' && ${state.accessor}.type === 'Point'`);
+        });
+        this.platform.serializer.serializeRegistry.registerClass(Coordinate, (_type, state) => {
+            state.addCodeForSetter(`
+                const c = ${state.accessor};
+                ${state.setter} = { type: 'Point', coordinates: [c.x, c.y] };
+            `);
+            state.ended = true;
+        });
+        this.platform.serializer.deserializeRegistry.registerClass(Coordinate, (_type, state) => {
+            state.addCodeForSetter(`
+                const c = ${state.accessor};
+                ${state.setter} = { x: c.coordinates[0], y: c.coordinates[1] };
+            `);
+            state.ended = true;
+        });
+
+        // when Jest mocks dates, the Date object checked by Deepkit is not the same as the one created by Jest
+        if (process.env.APP_ENV === 'test') {
+            const isDate = (t: Type) => t.kind === ReflectionKind.class && t.classType.name === 'Date';
+            this.platform.addType(isDate, 'datetime');
+            this.platform.addType(t => t.kind === ReflectionKind.union && t.types.filter(isNonUndefined).every(isDate), 'datetime');
+        }
+    }
+}
+
+export interface IMySQLDatabaseAdapterConfig extends PoolConfig {
+    enableLocksTable?: boolean;
+}
+export function createMySQLDatabase(
+    config: IMySQLDatabaseAdapterConfig,
+    entities: ConstructorParameters<typeof Database>[1] = []
+): ClassType<BaseDatabase<MySQLDatabaseAdapter>> {
+    return class extends BaseDatabase<MySQLDatabaseAdapter> {
+        constructor() {
+            const appConfig = getAppConfig();
+            const isProduction = appConfig.APP_ENV === 'production';
+
+            const { enableLocksTable, ...otherConfig } = config;
+
+            const adapter = new MySQLDatabaseAdapter({
+                host: appConfig.MYSQL_HOST,
+                port: appConfig.MYSQL_PORT,
+                user: appConfig.MYSQL_USER,
+                password: appConfig.MYSQL_PASSWORD_SECRET,
+                database: appConfig.MYSQL_DATABASE,
+                connectionLimit: appConfig.MYSQL_CONNECTION_LIMIT ?? (isProduction ? 10 : 5),
+                minimumIdle: appConfig.MYSQL_MIN_IDLE_CONNECTIONS ?? (isProduction ? undefined : 1),
+                idleTimeout: appConfig.MYSQL_IDLE_TIMEOUT_SECONDS ?? (isProduction ? 60 : 5),
+                allowPublicKeyRetrieval: true,
+                trace: true,
+                ...otherConfig
+            });
+
+            adapter.registerTransformations();
+
+            if (globalState.additionalEntities) {
+                entities.push(...globalState.additionalEntities);
+            }
+
+            super(adapter, entities);
+
+            if (enableLocksTable) {
+                this.rawExecute(
+                    `CREATE TABLE IF NOT EXISTS \`_locks\` (
+                        \`key\` VARCHAR(255) NOT NULL PRIMARY KEY,
+                        \`createdAt\` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
+                        \`lastTouched\` DATETIME
+                    )`
+                )
+                    .then(() => this.rawExecute(`DELETE FROM _locks WHERE lastTouched < NOW() - INTERVAL 1 HOUR`))
+                    .catch(err => {
+                        r(Logger).error(`Could not create _locks table: %s`, err);
+                    });
+            }
+        }
+    };
+}

package/src/database/postgres.ts

@@ -0,0 +1,97 @@
+import { ClassType } from '@deepkit/core';
+import { Logger } from '@deepkit/logger';
+import { Database, DatabaseSession } from '@deepkit/orm';
+import { PostgresConnection, PostgresDatabaseAdapter as BasePostgresDatabaseAdapter } from '@deepkit/postgres';
+import { isNonUndefined } from '@deepkit/sql';
+import { ReflectionKind, Type } from '@deepkit/type';
+import { PoolConfig } from 'pg';
+
+import { getAppConfig, r } from '../app/resolver';
+import { globalState } from '../app/state';
+import { BaseDatabase } from './common';
+
+export type PostgresDatabaseSession = DatabaseSession<PostgresDatabaseAdapter>;
+
+const originalRun = PostgresConnection.prototype.run;
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+PostgresConnection.prototype.run = async function (sql: string, params: any[] = []) {
+    await originalRun.call(this, sql, params);
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    return { affectedRows: (this as any).changes ?? 0, insertId: 0 } as any;
+};
+
+export class PostgresDatabaseAdapter extends BasePostgresDatabaseAdapter {
+    registerTransformations() {
+        // any
+        this.platform.serializer.deserializeRegistry.register(ReflectionKind.any, (_type, state) => {
+            state.addSetter(state.accessor);
+        });
+
+        // date string
+        this.platform.serializer.deserializeRegistry.addDecorator(
+            t => t.typeName === 'DateString',
+            (_type, state) => {
+                state.addSetter(`${state.accessor} instanceof Date ? ${state.accessor}.toISOString().substring(0, 10) : ${state.accessor}`);
+                state.ended = true;
+            }
+        );
+
+        // when Jest/test mocks dates, the Date object checked by Deepkit is not the same as the one created by the mock
+        if (process.env.APP_ENV === 'test') {
+            const isDate = (t: Type) => t.kind === ReflectionKind.class && t.classType.name === 'Date';
+            this.platform.addType(isDate, 'timestamp');
+            this.platform.addType(t => t.kind === ReflectionKind.union && t.types.filter(isNonUndefined).every(isDate), 'timestamp');
+        }
+    }
+}
+
+export interface IPostgresDatabaseAdapterConfig extends PoolConfig {
+    enableLocksTable?: boolean;
+}
+
+export function createPostgresDatabase(
+    config: IPostgresDatabaseAdapterConfig,
+    entities: ConstructorParameters<typeof Database>[1] = []
+): ClassType<BaseDatabase<PostgresDatabaseAdapter>> {
+    return class extends BaseDatabase<PostgresDatabaseAdapter> {
+        constructor() {
+            const appConfig = getAppConfig();
+            const isProduction = appConfig.APP_ENV === 'production';
+
+            const { enableLocksTable, ...otherConfig } = config;
+
+            const adapter = new PostgresDatabaseAdapter({
+                host: appConfig.PG_HOST,
+                port: appConfig.PG_PORT,
+                user: appConfig.PG_USER,
+                password: appConfig.PG_PASSWORD_SECRET,
+                database: appConfig.PG_DATABASE,
+                max: appConfig.PG_CONNECTION_LIMIT ?? (isProduction ? 10 : 5),
+                idleTimeoutMillis: (appConfig.PG_IDLE_TIMEOUT_SECONDS ?? (isProduction ? 60 : 5)) * 1000,
+                ...otherConfig
+            });
+
+            adapter.registerTransformations();
+
+            if (globalState.additionalEntities) {
+                entities.push(...globalState.additionalEntities);
+            }
+
+            super(adapter, entities);
+
+            if (enableLocksTable) {
+                this.rawExecute(
+                    `CREATE TABLE IF NOT EXISTS "_locks" (
+                        "key" VARCHAR(255) NOT NULL PRIMARY KEY,
+                        "createdAt" TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+                        "lastTouched" TIMESTAMP
+                    )`
+                )
+                    .then(() => this.rawExecute(`DELETE FROM "_locks" WHERE "lastTouched" < NOW() - INTERVAL '1 hour'`))
+                    .catch(err => {
+                        r(Logger).error(`Could not create _locks table: %s`, err);
+                    });
+            }
+        }
+    };
+}

package/src/database/types.ts

@@ -0,0 +1,18 @@
+import { TypeAnnotation } from '@deepkit/core';
+import { MySQL, Type, Validate, ValidatorError } from '@deepkit/type';
+
+export declare type UuidString = string & TypeAnnotation<'dksf:type', 'uuid'>;
+
+export class Coordinate {
+    x!: number;
+    y!: number;
+}
+export type MySQLCoordinate = Coordinate & MySQL<{ type: 'point' }>;
+export type NullableMySQLCoordinate = (Coordinate | null) & MySQL<{ type: 'point' }>;
+
+function _validateLength(value: string, _type: Type, length: number) {
+    if (typeof value === 'string' && value.length !== length) {
+        return new ValidatorError('invalidLength', `Value must be exactly ${length} characters long.`);
+    }
+}
+export declare type Length<T extends number> = string & Validate<typeof _validateLength, T> & TypeAnnotation<'dksf:length', T>;

package/src/devconsole/devconsole.controller.ts

@@ -0,0 +1,59 @@
+import { resolve } from 'path';
+
+import { http, HttpNotFoundError, HttpRequest, HttpResponse } from '@deepkit/http';
+import send from 'send';
+
+import { serializeOpenApiSchema } from '../app/dev';
+import { globalState } from '../app/state';
+import { DevConsoleLocalhostMiddleware } from './devconsole.middleware';
+
+const STATIC_DIR = resolve(__dirname, '../../devconsole');
+
+function serveStatic(req: HttpRequest, res: HttpResponse, path: string): Promise<void> {
+    return new Promise<void>((resolve, reject) => {
+        send(req, path, { root: STATIC_DIR })
+            .on('error', (err: { status: number }) => {
+                if (err.status === 404) {
+                    reject(new HttpNotFoundError());
+                } else {
+                    reject(err);
+                }
+            })
+            .on('end', resolve)
+            .pipe(res);
+    });
+}
+
+@(http.controller('/_devconsole').middleware(DevConsoleLocalhostMiddleware))
+export class DevConsoleController {
+    @http.GET('')
+    serveIndex(req: HttpRequest, res: HttpResponse): Promise<void> {
+        return serveStatic(req, res, 'index.html');
+    }
+
+    @http.GET('assets/:path')
+    serveAsset(path: string, req: HttpRequest, res: HttpResponse): Promise<void> {
+        return serveStatic(req, res, `assets/${path}`);
+    }
+
+    @http.GET('openapi.json')
+    serveOpenApiSchema(res: HttpResponse): void {
+        const app = globalState.currentApp;
+        if (!app) {
+            res.status(503);
+            res.setHeader('content-type', 'application/json');
+            res.end(JSON.stringify({ error: 'App not ready' }));
+            return;
+        }
+
+        try {
+            const schema = serializeOpenApiSchema(app);
+            res.setHeader('content-type', 'application/json; charset=utf-8');
+            res.end(JSON.stringify(schema, undefined, 2));
+        } catch (err) {
+            res.status(500);
+            res.setHeader('content-type', 'application/json');
+            res.end(JSON.stringify({ error: String(err) }));
+        }
+    }
+}

package/src/devconsole/devconsole.middleware.ts

@@ -0,0 +1,23 @@
+import { createHttpError, HttpRequest, HttpResponse } from '@deepkit/http';
+
+import { HttpMiddleware } from '../http/middleware';
+
+const HttpForbiddenError = createHttpError(403, 'Forbidden');
+
+export function isLocalhostDirect(request: { socket: { remoteAddress?: string }; headers: Record<string, string | string[] | undefined> }): boolean {
+    // Reject if request was forwarded through a reverse proxy
+    if (request.headers['x-forwarded-for'] || request.headers['x-real-ip']) {
+        return false;
+    }
+    const ip = request.socket.remoteAddress ?? '';
+    const normalized = ip.startsWith('::ffff:') ? ip.slice(7) : ip;
+    return normalized === '127.0.0.1' || ip === '::1';
+}
+
+export class DevConsoleLocalhostMiddleware extends HttpMiddleware {
+    handle(request: HttpRequest, _response: HttpResponse) {
+        if (!isLocalhostDirect(request)) {
+            throw new HttpForbiddenError();
+        }
+    }
+}

package/src/devconsole/devconsole.srpc.ts

@@ -0,0 +1,94 @@
+import type { DevConsoleStore } from './devconsole.store';
+import type { SrpcStream } from '../srpc/types';
+
+export interface SrpcMessageObserver {
+    onInboundMessage?(stream: SrpcStream, messageType: string, data: Record<string, unknown>): void;
+    onOutboundMessage?(stream: SrpcStream, messageType: string, data: Record<string, unknown>): void;
+    onConnectionEstablished?(stream: SrpcStream): void;
+    onConnectionClosed?(stream: SrpcStream, cause: string): void;
+}
+
+const BASE_MESSAGE_KEYS = new Set(['requestId', 'reply', 'error', 'userError', 'trace', 'pingPong', 'byteStreamOperation']);
+
+function identifyMessageType(data: Record<string, unknown>): string {
+    for (const key of Object.keys(data)) {
+        if (!BASE_MESSAGE_KEYS.has(key) && data[key] != null) {
+            return key;
+        }
+    }
+    return 'unknown';
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function sanitizeData(data: Record<string, any>): Record<string, unknown> {
+    const result: Record<string, unknown> = {};
+    for (const [key, value] of Object.entries(data)) {
+        if (key === 'trace') continue;
+        if (key === 'byteStreamOperation' && value) {
+            result[key] = {
+                streamId: value.streamId,
+                operation: value.write ? 'write' : value.finish ? 'finish' : value.destroy ? 'destroy' : 'unknown'
+            };
+            continue;
+        }
+        result[key] = value;
+    }
+    return result;
+}
+
+export function createDevConsoleSrpcObserver(store: DevConsoleStore): SrpcMessageObserver {
+    return {
+        onInboundMessage(stream: SrpcStream, messageType: string, data: Record<string, unknown>) {
+            const conn = store.srpcConnections.get(stream.id);
+            if (conn) conn.messageCount++;
+
+            store.addSrpcMessage({
+                id: (data.requestId as string) ?? '',
+                timestamp: Date.now(),
+                streamId: stream.id,
+                clientId: stream.clientId,
+                direction: 'inbound',
+                messageType,
+                isReply: !!data.reply,
+                data: sanitizeData(data),
+                error: data.error as string | undefined,
+                isUserError: data.userError as boolean | undefined
+            });
+        },
+
+        onOutboundMessage(stream: SrpcStream, messageType: string, data: Record<string, unknown>) {
+            store.addSrpcMessage({
+                id: (data.requestId as string) ?? '',
+                timestamp: Date.now(),
+                streamId: stream.id,
+                clientId: stream.clientId,
+                direction: 'outbound',
+                messageType,
+                isReply: !!data.reply,
+                data: sanitizeData(data),
+                error: data.error as string | undefined,
+                isUserError: data.userError as boolean | undefined
+            });
+        },
+
+        onConnectionEstablished(stream: SrpcStream) {
+            store.addSrpcConnection({
+                streamId: stream.id,
+                clientId: stream.clientId,
+                clientStreamId: stream.clientStreamId,
+                appVersion: stream.appVersion,
+                address: stream.address,
+                connectedAt: stream.connectedAt,
+                lastPingAt: stream.lastPingAt,
+                meta: stream.meta as Record<string, unknown>,
+                messageCount: 0
+            });
+        },
+
+        onConnectionClosed(stream: SrpcStream, cause: string) {
+            store.removeSrpcConnection(stream.id, stream.clientId, cause);
+        }
+    };
+}
+
+export { identifyMessageType, sanitizeData };

package/src/devconsole/devconsole.store.ts

@@ -0,0 +1,190 @@
+export class RingBuffer<T> {
+    private buffer: (T | undefined)[];
+    private head = 0;
+    private count = 0;
+
+    constructor(private capacity: number) {
+        this.buffer = Array.from({ length: capacity });
+    }
+
+    push(item: T): void {
+        this.buffer[this.head] = item;
+        this.head = (this.head + 1) % this.capacity;
+        if (this.count < this.capacity) this.count++;
+    }
+
+    toArray(): T[] {
+        if (this.count === 0) return [];
+        if (this.count < this.capacity) {
+            return this.buffer.slice(0, this.count) as T[];
+        }
+        return [...this.buffer.slice(this.head), ...this.buffer.slice(0, this.head)] as T[];
+    }
+
+    get length(): number {
+        return this.count;
+    }
+}
+
+export interface DevConsoleErrorInfo {
+    name: string;
+    message: string;
+    stack?: string;
+    cause?: DevConsoleErrorInfo;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    [key: string]: any;
+}
+
+export interface DevConsoleHttpEntry {
+    id: string;
+    timestamp: number;
+    method: string;
+    url: string;
+    remoteAddress: string;
+    requestHeaders: Record<string, string | string[] | undefined>;
+    requestBody: string | null;
+    statusCode: number;
+    responseHeaders: Record<string, string | string[] | undefined>;
+    responseBody: string | null;
+    durationMs: number;
+    error?: DevConsoleErrorInfo;
+}
+
+export interface DevConsoleSrpcMessage {
+    id: string;
+    timestamp: number;
+    streamId: string;
+    clientId: string;
+    direction: 'inbound' | 'outbound';
+    messageType: string;
+    isReply: boolean;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    data: Record<string, any>;
+    error?: string;
+    isUserError?: boolean;
+}
+
+export interface DevConsoleSrpcConnection {
+    streamId: string;
+    clientId: string;
+    clientStreamId: string;
+    appVersion: string;
+    address: string;
+    connectedAt: number;
+    lastPingAt: number;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    meta: Record<string, any>;
+    messageCount: number;
+}
+
+export interface DevConsoleSrpcDisconnection {
+    streamId: string;
+    clientId: string;
+    disconnectedAt: number;
+    cause: string;
+}
+
+export interface DevConsoleMutexEntry {
+    id: string;
+    key: string;
+    status: 'pending' | 'acquired' | 'released' | 'error' | 'failed';
+    startedAt: number;
+    acquiredAt?: number;
+    releasedAt?: number;
+    durationMs?: number;
+    waitDurationMs?: number;
+    waited?: boolean;
+    error?: string;
+}
+
+export class DevConsoleStore {
+    private static instance: DevConsoleStore | null = null;
+
+    readonly httpEntries = new RingBuffer<DevConsoleHttpEntry>(500);
+    readonly srpcMessages = new RingBuffer<DevConsoleSrpcMessage>(500);
+    readonly srpcConnections = new Map<string, DevConsoleSrpcConnection>();
+    readonly srpcDisconnected = new RingBuffer<DevConsoleSrpcDisconnection>(50);
+    readonly mutexEntries = new RingBuffer<DevConsoleMutexEntry>(200);
+    readonly activeMutexes = new Map<string, DevConsoleMutexEntry>();
+    readonly startedAt = Date.now();
+
+    onEvent?: (type: string, data: unknown) => void;
+
+    addHttpEntry(entry: DevConsoleHttpEntry) {
+        this.httpEntries.push(entry);
+        this.onEvent?.('http:entry', entry);
+    }
+
+    addSrpcMessage(msg: DevConsoleSrpcMessage) {
+        this.srpcMessages.push(msg);
+        this.onEvent?.('srpc:message', msg);
+    }
+
+    addSrpcConnection(conn: DevConsoleSrpcConnection) {
+        this.srpcConnections.set(conn.streamId, conn);
+        this.onEvent?.('srpc:connection', conn);
+    }
+
+    removeSrpcConnection(streamId: string, clientId: string, cause: string) {
+        this.srpcConnections.delete(streamId);
+        const disc: DevConsoleSrpcDisconnection = { streamId, clientId, disconnectedAt: Date.now(), cause };
+        this.srpcDisconnected.push(disc);
+        this.onEvent?.('srpc:disconnection', disc);
+    }
+
+    addMutexPending(entry: DevConsoleMutexEntry) {
+        this.mutexEntries.push(entry);
+        this.activeMutexes.set(entry.id, entry);
+        this.onEvent?.('mutex:pending', entry);
+    }
+
+    updateMutexAcquired(id: string, waited: boolean) {
+        const entry = this.activeMutexes.get(id);
+        if (entry) {
+            entry.status = 'acquired';
+            entry.acquiredAt = Date.now();
+            entry.waitDurationMs = entry.acquiredAt - entry.startedAt;
+            entry.waited = waited;
+            this.onEvent?.('mutex:acquired', entry);
+        }
+    }
+
+    updateMutexReleased(id: string) {
+        const entry = this.activeMutexes.get(id);
+        if (entry) {
+            entry.status = 'released';
+            entry.releasedAt = Date.now();
+            entry.durationMs = entry.releasedAt - (entry.acquiredAt ?? entry.startedAt);
+            this.activeMutexes.delete(id);
+            this.onEvent?.('mutex:released', entry);
+        }
+    }
+
+    updateMutexError(id: string, err: unknown) {
+        const entry = this.activeMutexes.get(id);
+        if (entry) {
+            entry.status = 'error';
+            entry.releasedAt = Date.now();
+            entry.durationMs = entry.releasedAt - (entry.acquiredAt ?? entry.startedAt);
+            entry.error = err instanceof Error ? err.message : String(err);
+            this.activeMutexes.delete(id);
+            this.onEvent?.('mutex:error', entry);
+        }
+    }
+
+    addMutexFailed(entry: DevConsoleMutexEntry) {
+        this.mutexEntries.push(entry);
+        this.onEvent?.('mutex:failed', entry);
+    }
+
+    static init(): DevConsoleStore {
+        if (!this.instance) {
+            this.instance = new DevConsoleStore();
+        }
+        return this.instance;
+    }
+
+    static get(): DevConsoleStore | null {
+        return this.instance;
+    }
+}