@feasibleone/blong-gogo 1.26.0 → 1.28.0

package/src/Log.ts

@@ -1,5 +1,6 @@
+import {withProgress} from '@feasibleone/blong-lib';
 import {Internal, type ILog, type ILogger} from '@feasibleone/blong/types';
-import {pino, type LogFn, type Logger, type LoggerOptions} from 'pino';
+import {pino, type Logger, type LoggerOptions} from 'pino';
 import {monotonicFactory} from 'ulidx';
 import type {CacacheTransportOptions} from './pino-cacache.js';
 
@@ -28,14 +29,31 @@ const ignoreArgPatterns = [
 // execArgv to [], stripping the TypeScript loader.  We work around this by
 // explicitly forwarding process.execArgv so the TypeScript loader is available
 // inside the transport worker thread.
+//
+// However, when the process is started under `tap` (e.g. `blong-dev test`),
+// process.execArgv contains tap's own `--import` hooks (@tapjs/typescript →
+// pirates/ts-node). Those hooks intercept `.ts` loads in the worker and bypass
+// Node's native type stripping, which fails on `import type` constructs
+// (SyntaxError: Unexpected identifier 'PinoPretty' in pino-pretty.ts). So we
+// drop tap's hooks from the worker execArgv.
+//
+// Dropping the hooks alone is not enough: pino's multi-target transport loads
+// `.ts`/`.cts` targets with `realRequire()` (CJS require, relying on ts-node),
+// which fails regardless of execArgv. We therefore point both transports at
+// tiny `.mjs` shims (pino-pretty.mjs / pino-cacache.mjs) that re-export the
+// `.ts` modules. Pino then treats them as non-TypeScript targets and loads
+// them with `realImport()` (dynamic ESM import), where Node's native type
+// stripping handles the re-exported `.ts` — in both tap and normal dev runs.
 const WORKER_OPTS = {
     execArgv: process.execArgv.filter(
-        arg => !ignoreArgPatterns.some(pattern => arg.startsWith(pattern)),
+        arg =>
+            !ignoreArgPatterns.some(pattern => arg.startsWith(pattern)) &&
+            !(arg.startsWith('--import=') && arg.includes('@tapjs')),
     ),
 };
 
 const PRETTY_TRANSPORT = {
-    target: './pino-pretty.ts',
+    target: './pino-pretty.mjs',
     worker: WORKER_OPTS,
     options: {
         singleLine: true,
@@ -77,7 +95,7 @@ export default class Log extends Internal implements ILog {
                 targets: [
                     PRETTY_TRANSPORT,
                     {
-                        target: './pino-cacache.ts',
+                        target: './pino-cacache.mjs',
                         worker: WORKER_OPTS,
                         options: cacacheOptions,
                     },
@@ -99,13 +117,13 @@ export default class Log extends Internal implements ILog {
         bindings: object,
     ): ReturnType<ILog['logger']> {
         const child = this.#logger.child(bindings, {level});
-        const result: Record<keyof ILogger, LogFn | null> = {
-            trace: null,
-            debug: null,
-            info: null,
-            warn: null,
-            error: null,
-            fatal: null,
+        const result: ILogger = {
+            trace: undefined,
+            debug: undefined,
+            info: undefined,
+            warn: undefined,
+            error: undefined,
+            fatal: undefined,
         };
         switch (level) {
             case 'trace':
@@ -121,6 +139,9 @@ export default class Log extends Internal implements ILog {
             case 'fatal':
                 result.fatal = child.fatal.bind(child);
         }
-        return result as unknown as ILogger;
+        return {
+            ...result,
+            progress: (label, promise, options) => withProgress(result, label, promise, options),
+        };
     }
 }

package/src/Registry.ts

@@ -55,6 +55,10 @@ export default class Registry extends Internal implements IRegistry {
     public ports: Map<string, IAdapterRegistry> = new Map();
     public methods: Map<string, Handlers> = new Map();
     public objectSchema: IObjectSchema = {};
+    #stopped = false;
+    #logger:
+        | {info?: (...args: unknown[]) => void; warn?: (...args: unknown[]) => void}
+        | undefined = undefined;
     #reload: PQueue = new PQueue({concurrency: 1});
     #ports: Map<string, Adapter> = new Map();
     #error: IErrorFactory;
@@ -217,6 +221,7 @@ export default class Registry extends Internal implements IRegistry {
             callback = port as MatchMethodsCallback;
             port = undefined;
         }
+        const log = this.#log.logger('info', {name: 'registry'});
         for (const [name, value] of this.methods.entries()) {
             if (
                 ([] as (string | RegExp)[])
@@ -228,7 +233,20 @@ export default class Registry extends Internal implements IRegistry {
             ) {
                 if (mode === 'merge') {
                     for (const item of value) {
+                        const started = Date.now();
                         const {local, literals} = await this._createHandlers([item], port);
+                        // Visibility: a handler factory that hangs (e.g. a
+                        // `subject.validation` resolving a model handler whose
+                        // derived name doesn't match a registered file) would
+                        // otherwise stall startup silently. Warn after a slow
+                        // threshold so the stuck method is identified.
+                        const elapsed = Date.now() - started;
+                        if (elapsed > 3_000) {
+                            log.warn?.(
+                                `registry handler factory for '${name}' took ${elapsed}ms — ` +
+                                    'a hanging dependency (e.g. an unresolvable remote method) is likely',
+                            );
+                        }
                         callback!(name, local, literals);
                     }
                 } else {
@@ -255,9 +273,17 @@ export default class Registry extends Internal implements IRegistry {
                           ? validation
                           : {};
                 if (typeof validation === 'function') name = validation.name;
-                const prev = this.#validations[methodParts(name)];
-                if (prev) merge(prev, schema);
-                else this.#validations[methodParts(name)] = schema as GatewaySchema;
+                // A later-registered validation REPLACES an earlier one for the
+                // same methodParts key instead of merging. `subject.validation`
+                // (blong-server, `srv`) registers first and auto-generates the
+                // CRUD validations for every `public: true` model; an explicit
+                // realm gateway file (`gateway/<subject>/<method>.ts`) registers
+                // later and must reliably WIN for the operation it overrides.
+                // Merging TypeBox schemas with ut-function.merge also corrupts
+                // symbol-keyed Kind markers on nested schemas (e.g. a `details`
+                // array) and lets auto-required fields leak into the override,
+                // so replace instead. Unrelated keys still merge normally.
+                this.#validations[methodParts(name)] = schema as GatewaySchema;
             });
         });
         return this.#validations;
@@ -374,10 +400,49 @@ export default class Registry extends Internal implements IRegistry {
     }
 
     public async start(configOverride: object): Promise<IRegistry> {
+        this.#stopped = false;
+
         await this._collectObjectSchema();
-        for (const id of Array.from(this.ports.keys())) await this.createPort(id);
-        for (const port of this.#ports.values()) await port.start(configOverride);
-        for (const port of this.#ports.values()) await port.ready();
+        this.#logger = this.#log.logger('info', {name: 'registry'});
+        let created = 0;
+        const portIds = Array.from(this.ports.keys());
+        await blongLib.withProgress(
+            this.#logger,
+            'create ports',
+            (async () => {
+                for (const id of portIds) {
+                    await this.createPort(id);
+                    created += 1;
+                }
+            })(),
+            {getProgress: () => ({done: created, total: portIds.length})},
+        );
+        let started = 0;
+        const startPorts = Array.from(this.#ports.values());
+        await blongLib.withProgress(
+            this.#logger,
+            'start ports',
+            (async () => {
+                for (const port of startPorts) {
+                    await port.start(configOverride);
+                    started += 1;
+                }
+            })(),
+            {getProgress: () => ({done: started, total: startPorts.length})},
+        );
+        let ready = 0;
+        const readyPorts = Array.from(this.#ports.values());
+        await blongLib.withProgress(
+            this.#logger,
+            'ready ports',
+            (async () => {
+                for (const port of readyPorts) {
+                    await port.ready();
+                    ready += 1;
+                }
+            })(),
+            {getProgress: () => ({done: ready, total: readyPorts.length})},
+        );
         this.#gateway?.route(await this._validations(), {name: '', version: ''});
         await this.#resolution?.start();
         await this.#rpcServer?.start();
@@ -405,12 +470,27 @@ export default class Registry extends Internal implements IRegistry {
     }
 
     public async stop(): Promise<IRegistry> {
+        if (this.#stopped) return this;
         await this.#watch?.stop();
         await this.#gateway?.stop();
         await this.#remote?.stop();
         await this.#rpcServer?.stop();
         await this.#resolution?.stop();
-        for (const port of this.#ports.values()) await port.stop();
+        let stopped = 0;
+        const ports = Array.from(this.#ports.values());
+        await blongLib.withProgress(
+            this.#logger,
+            'stop ports',
+            (async () => {
+                for (const port of ports) {
+                    await port.stop();
+                    stopped += 1;
+                }
+            })(),
+            {getProgress: () => ({done: stopped, total: ports.length})},
+        );
+        this.#stopped = true;
+        this.#logger = undefined;
         return this;
     }
 

package/src/Remote.ts

@@ -204,6 +204,18 @@ export default class Remote extends Internal implements IRemote {
                 if (methodName && !this.gateway?.($applyMeta, methodName)) {
                     if (this.#config.canSkipSocket) fn = this._findMethod(methodName, methodType);
                     if (fn) unpack = true;
+                    else if (methodName && this.#config.canSkipSocket) {
+                        // Visibility: under canSkipSocket every call is expected
+                        // to resolve locally. A missing method (e.g. a derived
+                        // handler name that doesn't match a registered file —
+                        // `$subject$objectModel` vs `$subject$ObjectModel`) would
+                        // otherwise fail or hang silently. Name it so the typo /
+                        // case / placeholder mismatch is obvious.
+                        this.log?.warn?.({
+                            $meta: {mtid: 'event', method: 'remote.methodNotFound'},
+                            message: `remote method not found locally: '${methodName}'`,
+                        });
+                    }
                 }
                 if (!fn) {
                     fn = this.sender(methodType, typeName);

package/src/Watch.ts

@@ -1,3 +1,4 @@
+import {withProgress} from '@feasibleone/blong-lib';
 import {
     handler,
     Internal,
@@ -47,6 +48,7 @@ const isLayerActivation = (filename: string): boolean =>
     /^layer\.(server|browser)\.[mc]?[tj]sx?$/i.test(filename);
 const isConfig = (filename: string): boolean => /^config\.[mc]?[tj]sx?$/i.test(filename);
 const isPlay = (filename: string): boolean => /\.play\.[mc]?[tj]sx?$/i.test(filename);
+const isTest = (filename: string): boolean => /\.test\.[mc]?[tj]sx?$/i.test(filename);
 
 const prefixRE: RegExp = /(?:\d+-)?(.*)/;
 
@@ -195,7 +197,8 @@ export default class Watch extends Internal implements IWatch {
             },
             [[] as string[], [] as string[]],
         );
-        const {Formatter, TypeScriptToTypeBox} = await import('@sinclair/typebox-codegen');
+        const codeGen = '@sinclair/typebox-codegen';
+        const {Formatter, TypeScriptToTypeBox} = await import(/* @vite-ignore */ codeGen);
         if (schema.length)
             this.#platform.writeFileSync(
                 this.#platform.join(dir, '~.schema.ts'),
@@ -288,7 +291,8 @@ export default class Watch extends Internal implements IWatch {
                     isCode(entry.name) &&
                     !isLayerActivation(entry.name) &&
                     !isConfig(entry.name) &&
-                    !isPlay(entry.name),
+                    !isPlay(entry.name) &&
+                    !isTest(entry.name),
             );
         await this.#apiSchema?.generateDir(dir, handlerFiles as Dirent[]);
         for (const handlerEntry of handlerFiles) {
@@ -312,7 +316,11 @@ export default class Watch extends Internal implements IWatch {
                       ).default
                     : ((await directory![filename]()) as {default: unknown}).default;
             if (!item) {
-                this.log?.error?.('Error loading ' + filename);
+                this.log?.error?.(
+                    'Error loading ' +
+                        filename +
+                        ' ; probably a generic source code was put in a handler group folder',
+                );
                 continue;
             }
             const expectedName = this.#platform.basename(
@@ -396,7 +404,8 @@ export default class Watch extends Internal implements IWatch {
             if (
                 isCode(filename) &&
                 !isLayerActivation(this.#platform.basename(filename)) &&
-                !isPlay(this.#platform.basename(filename))
+                !isPlay(this.#platform.basename(filename)) &&
+                !isTest(this.#platform.basename(filename))
             ) {
                 const item =
                     typeof isFile === 'function'
@@ -478,27 +487,36 @@ export default class Watch extends Internal implements IWatch {
         const affected = affectedNamespaces(diff, registry.ports.keys());
         const next = this.#configRuntime.snapshot;
 
-        for (const portId of affected) {
-            const portInstance = await registry.getPort(portId);
-            if (!portInstance) continue;
-
-            if (typeof portInstance['configChanged'] === 'function') {
-                // Adapter supports the configChanged hook — zero-downtime update
-                try {
-                    await portInstance['configChanged'](diff, next, prev);
-                } catch (error) {
-                    this.log?.error?.(error);
-                }
-            } else {
-                // Fallback: stop and restart the port with the current configOverride
-                await portInstance.stop();
-                const fresh = await registry.createPort(portId);
-                if (fresh) {
-                    await fresh.start(configOverride);
-                    await fresh.ready();
+        let reloaded = 0;
+        await withProgress(
+            this.log,
+            'reload config',
+            (async () => {
+                for (const portId of affected) {
+                    const portInstance = await registry.getPort(portId);
+                    if (portInstance) {
+                        if (typeof portInstance['configChanged'] === 'function') {
+                            // Adapter supports the configChanged hook — zero-downtime update
+                            try {
+                                await portInstance['configChanged'](diff, next, prev);
+                            } catch (error) {
+                                this.log?.error?.(error);
+                            }
+                        } else {
+                            // Fallback: stop and restart the port with the current configOverride
+                            await portInstance.stop();
+                            const fresh = await registry.createPort(portId);
+                            if (fresh) {
+                                await fresh.start(configOverride);
+                                await fresh.ready();
+                            }
+                        }
+                    }
+                    reloaded += 1;
                 }
-            }
-        }
+            })(),
+            {getProgress: () => ({done: reloaded, total: affected.size})},
+        );
 
         this.#emit.dispatchEvent(new Event('test'));
     }
@@ -671,8 +689,19 @@ export default class Watch extends Internal implements IWatch {
                             return result;
                         }),
                     );
-                    await Promise.all(
-                        steps.map(step => chain(step as Parameters<typeof chain>[0])),
+                    let executed = 0;
+                    await withProgress(
+                        this.log,
+                        'run test groups',
+                        (async () => {
+                            await Promise.all(
+                                steps.map(async step => {
+                                    await chain(step as Parameters<typeof chain>[0]);
+                                    executed += 1;
+                                }),
+                            );
+                        })(),
+                        {getProgress: () => ({done: executed, total: steps.length})},
                     );
                 } catch (error) {
                     this.log?.error?.(error);

package/src/adapter/browser/http.ts

@@ -23,6 +23,8 @@ const errorMap: IErrorMap = {
 };
 
 let _errors: Errors<typeof errorMap>;
+const undici = 'undici';
+const nodeFs = 'node:fs';
 
 export default adapter<IConfig>(({utError, manifest}) => {
     _errors ||= utError.register(errorMap);
@@ -51,8 +53,8 @@ export default adapter<IConfig>(({utError, manifest}) => {
                 // Dynamic imports — only run on the server; @vite-ignore prevents
                 // Vite from trying to bundle these Node.js-only modules for the browser.
                 const [{Agent}, {readFileSync}] = await Promise.all([
-                    import(/* @vite-ignore */ 'undici') as Promise<typeof import('undici')>,
-                    import(/* @vite-ignore */ 'node:fs') as Promise<typeof import('node:fs')>,
+                    import(/* @vite-ignore */ undici) as Promise<typeof import('undici')>,
+                    import(/* @vite-ignore */ nodeFs) as Promise<typeof import('node:fs')>,
                 ]);
                 const {tls} = this.config;
                 const agent = new Agent({

package/src/adapter/schema/knex/binary.ts

@@ -26,7 +26,12 @@ for (let i = 0; i < CROCKFORD.length; i++) CROCKFORD_REV[CROCKFORD[i]] = i;
 // ── Public API ───────────────────────────────────────────────────────────────
 
 /**
- * Discover binary(16) columns from INFORMATION_SCHEMA.
+ * Discover binary(16) / varbinary(16) columns from INFORMATION_SCHEMA.
+ *
+ * `type.uuid()` columns are created as fixed `binary(16)` while `type.uid*()`
+ * columns (and most FK columns) are created as `varbinary(16)` by knex's
+ * `table.binary()`.  Both are 16-byte UUID columns and need the same
+ * string ↔ Buffer conversion, so BOTH `binary` and `varbinary` are matched.
  *
  * Call this once during adapter `ready()`, after the schema has been synced,
  * and store the result on `this.config.context.binaryColumns`.
@@ -34,10 +39,8 @@ for (let i = 0; i < CROCKFORD.length; i++) CROCKFORD_REV[CROCKFORD[i]] = i;
 export async function discoverBinaryColumns(knex: Knex): Promise<Map<string, Set<string>>> {
     const rows: Array<{TABLE_NAME: string; COLUMN_NAME: string}> = await knex
         .from('INFORMATION_SCHEMA.COLUMNS')
-        .where({
-            DATA_TYPE: 'binary',
-            CHARACTER_MAXIMUM_LENGTH: 16,
-        })
+        .whereIn('DATA_TYPE', ['binary', 'varbinary'])
+        .andWhere('CHARACTER_MAXIMUM_LENGTH', 16)
         .select('TABLE_NAME', 'COLUMN_NAME');
     const map = new Map<string, Set<string>>();
     for (const row of rows) {

package/src/adapter/schema/knex/database.test.ts

@@ -0,0 +1,87 @@
+/**
+ * Unit tests for the `ensureDatabase` helper (adapter/schema/knex/database.ts).
+ *
+ * `ensureDatabase` accepts an injectable `connect` factory, so these tests use
+ * a fake admin connection and never touch a real MySQL server.
+ */
+
+import {test} from 'tap';
+
+import {ensureDatabase, type IAdminConnection} from './database.ts';
+
+interface IFakeState {
+    calls: string[];
+    rows?: Array<{SCHEMA_NAME: string}>;
+    createError?: Error;
+}
+
+function fakeConnect(state: IFakeState): () => Promise<IAdminConnection> {
+    return async () => {
+        const admin: IAdminConnection = {
+            async query<T>(sql: string): Promise<[T, unknown]> {
+                state.calls.push(sql);
+                if (sql.startsWith('SELECT SCHEMA_NAME')) {
+                    return [(state.rows ?? []) as T, []];
+                }
+                if (state.createError) throw state.createError;
+                return [undefined as T, []];
+            },
+            async end() {
+                state.calls.push('end');
+            },
+        };
+        return admin;
+    };
+}
+
+test('ensureDatabase — returns early when no database is configured', async t => {
+    const state: IFakeState = {calls: []};
+    const result = await ensureDatabase({host: 'localhost'}, fakeConnect(state));
+    t.same(result, {created: false, database: ''}, 'no-op result');
+    t.equal(state.calls.length, 0, 'no connection made');
+    t.end();
+});
+
+test('ensureDatabase — creates the database when missing', async t => {
+    const state: IFakeState = {calls: [], rows: []};
+    const result = await ensureDatabase({database: 'blong-kalin'}, fakeConnect(state));
+    t.equal(result.created, true, 'database was created');
+    t.equal(result.database, 'blong-kalin', 'reports the database name');
+    t.ok(
+        state.calls.some(c => c.startsWith('CREATE DATABASE')),
+        'CREATE DATABASE issued',
+    );
+    t.equal(state.calls[state.calls.length - 1], 'end', 'admin connection closed');
+    t.end();
+});
+
+test('ensureDatabase — skips creation when the database exists', async t => {
+    const state: IFakeState = {calls: [], rows: [{SCHEMA_NAME: 'blong-kalin'}]};
+    const result = await ensureDatabase({database: 'blong-kalin'}, fakeConnect(state));
+    t.equal(result.created, false, 'database already exists');
+    t.ok(
+        !state.calls.some(c => c.startsWith('CREATE DATABASE')),
+        'no CREATE DATABASE issued',
+    );
+    t.equal(state.calls[state.calls.length - 1], 'end', 'admin connection closed');
+    t.end();
+});
+
+test('ensureDatabase — rejects when CREATE DATABASE fails but still closes the connection', async t => {
+    const state: IFakeState = {
+        calls: [],
+        rows: [],
+        createError: new Error('access denied'),
+    };
+    await t.rejects(ensureDatabase({database: 'blong-kalin'}, fakeConnect(state)), /access denied/);
+    t.equal(state.calls[state.calls.length - 1], 'end', 'admin connection closed on failure');
+    t.end();
+});
+
+test('ensureDatabase — escapes backticks in the database name', async t => {
+    const state: IFakeState = {calls: [], rows: []};
+    await ensureDatabase({database: 'weird`db'}, fakeConnect(state));
+    const createSql = state.calls.find(c => c.startsWith('CREATE DATABASE'));
+    t.ok(createSql?.includes('`weird``db`'), 'backtick doubled in identifier');
+    t.end();
+});

package/src/adapter/schema/knex/database.ts

@@ -0,0 +1,67 @@
+/**
+ * `ensureDatabase` — create the MySQL database if it does not exist.
+ *
+ * Used by the knex adapter (`adapter/server/knex.ts`) before building the real
+ * pool when `knex.createDatabase` is enabled (default on in the `dev` intent via
+ * the shared `srv.db` adapter). Connects WITHOUT a database, checks
+ * `information_schema.schemata`, and issues `CREATE DATABASE` when the schema is
+ * missing. On failure the caller decides whether to warn-and-continue (schema
+ * sync will surface the real error) or fail.
+ */
+
+import {createConnection} from 'mysql2/promise';
+
+export interface IEnsureDatabaseOptions {
+    host?: string;
+    port?: number;
+    user?: string;
+    password?: string;
+    database?: string;
+}
+
+export interface IEnsureDatabaseResult {
+    /** Whether the database had to be created (false when it already existed). */
+    created: boolean;
+    /** The database name that was checked / created. */
+    database: string;
+}
+
+/** The minimal admin-connection surface used by `ensureDatabase`. */
+export interface IAdminConnection {
+    query<T>(sql: string, params?: unknown[]): Promise<[T, unknown]>;
+    end(): Promise<void>;
+}
+
+type IConnect = (config: Record<string, unknown>) => Promise<IAdminConnection>;
+
+/**
+ * Try to create `database` if it does not exist. Resolves `{created, database}`
+ * on success; rejects if the server cannot be reached or `CREATE DATABASE`
+ * fails. `connect` is injectable for tests (defaults to `mysql2`).
+ */
+export async function ensureDatabase(
+    options: IEnsureDatabaseOptions,
+    connect: IConnect = createConnection as unknown as IConnect,
+): Promise<IEnsureDatabaseResult> {
+    const database = options.database;
+    if (!database) return {created: false, database: ''};
+    const admin = await connect({
+        host: options.host ?? 'localhost',
+        port: options.port ?? 3306,
+        user: options.user,
+        password: options.password,
+    });
+    try {
+        const [rows] = await admin.query<Array<{SCHEMA_NAME: string}>>(
+            'SELECT SCHEMA_NAME FROM information_schema.schemata WHERE SCHEMA_NAME = ?',
+            [database],
+        );
+        if (rows.length > 0) return {created: false, database};
+        await admin.query(
+            `CREATE DATABASE \`${database.replaceAll('`', '``')}\` CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci`,
+        );
+        return {created: true, database};
+    } finally {
+        await admin.end();
+    }
+}