@gloocan/cat-inspector 0.1.1

package/dist/decorators/cat.js

@@ -0,0 +1,102 @@
+import 'reflect-metadata';
+import { ActiveContext, ApiContext, ErrorCapture, Registry, registerClassConstructor, broadcastErrorThrown, } from '../registry-state.js';
+import { extractParamNames, extractApiReturnLabels, getFunctionBody, extractReturnLabels, extractThrowLabels, } from '../source-utils.js';
+export function Cat(target, key, descriptor) {
+    const fn = descriptor.value;
+    const ctor = target.constructor;
+    const className = ctor.name ?? '';
+    const fnKey = `${className}.${key}`;
+    if (className)
+        registerClassConstructor(className, ctor);
+    const body = getFunctionBody(fn);
+    const paramMeta = Reflect.getMetadata('design:paramtypes', target, key) ?? [];
+    const returnMeta = Reflect.getMetadata('design:returntype', target, key);
+    const staticLabels = extractReturnLabels(body);
+    const staticThrowLabels = extractThrowLabels(body);
+    const staticApiReturnLabels = extractApiReturnLabels(body);
+    const paramTypeNames = paramMeta.map((t) => t?.name ?? 'unknown');
+    const isApiCandidate = paramTypeNames.includes('Request') && paramTypeNames.includes('Response');
+    Registry.set(fnKey, {
+        mode: isApiCandidate ? 'api_candidate' : 'service',
+        className,
+        method: key,
+        style: 'class',
+        body,
+        params: extractParamNames(fn).map((name, i) => ({
+            name,
+            type: paramMeta[i]?.name ?? 'unknown',
+        })),
+        declaredReturn: returnMeta?.name ?? 'void',
+        returns: staticLabels.map((label) => ({
+            label,
+            type: null,
+            status: 'pending',
+        })),
+        errors: staticThrowLabels.map((label) => ({
+            label,
+            type: null,
+            message: null,
+            status: 'pending',
+        })),
+        children: [],
+        parents: [],
+        route: null,
+        httpMethod: null,
+        apiResponses: staticApiReturnLabels.map((label) => ({
+            label,
+            statusCode: null,
+            bodyShape: null,
+            status: 'pending',
+        })),
+        serviceLinks: [],
+        pipelineId: null,
+        pipelineIndex: null,
+        originalFn: fn,
+    });
+    const original = fn;
+    const isThenable = (v) => Boolean(v && typeof v.then === 'function');
+    const wrapped = function (...args) {
+        const entry = Registry.get(fnKey);
+        const isApi = entry?.mode === 'api';
+        const clearContext = () => {
+            if (isApi)
+                ApiContext.clear();
+            else
+                ActiveContext.pop();
+        };
+        if (isApi)
+            ApiContext.set(fnKey);
+        else
+            ActiveContext.push(fnKey);
+        let out;
+        try {
+            out = original.apply(this, args);
+        }
+        catch (err) {
+            if (err instanceof Error && !ErrorCapture.hasCurrent()) {
+                ErrorCapture.capture('UNEXPECTED_ERROR', err);
+                broadcastErrorThrown({
+                    event: 'ERROR_THROWN',
+                    fnKey,
+                    label: 'UNEXPECTED_ERROR',
+                    layer: 'unexpected',
+                    message: err.message,
+                    stack: err.stack ?? null,
+                });
+            }
+            clearContext();
+            throw err;
+        }
+        if (isThenable(out)) {
+            return Promise.resolve(out).finally(clearContext);
+        }
+        clearContext();
+        return out;
+    };
+    descriptor.value = wrapped;
+    const entry = Registry.get(fnKey);
+    if (entry)
+        entry.originalFn = wrapped;
+    return descriptor;
+}
+//# sourceMappingURL=cat.js.map

package/dist/decorators/cat.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cat.js","sourceRoot":"","sources":["../../src/decorators/cat.ts"],"names":[],"mappings":"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"}

package/dist/express-inspector-correlation.d.ts

@@ -0,0 +1,23 @@
+import type { RequestHandler } from 'express';
+import type { InspectorBroadcastSource } from './registry-state.js';
+/**
+ * Non-enumerable request metadata so HTTP inspector broadcasts stay correlated when
+ * middleware defers `next()` (multipart parsers, microtasks, etc.) and AsyncLocalStorage
+ * from an outer scope is no longer active.
+ */
+export declare const INSPECTOR_HTTP_META: unique symbol;
+export type InspectorHttpRequestMeta = {
+    socketId: string;
+    correlationId: string;
+    source: Extract<InspectorBroadcastSource, 'http'>;
+};
+export declare function attachInspectorHttpMeta(req: object, meta: InspectorHttpRequestMeta): void;
+/** Read metadata attached by {@link createInspectorCorrelationMiddleware}. */
+export declare function readInspectorHttpMeta(req: unknown): InspectorHttpRequestMeta | undefined;
+/**
+ * When `X-Socket-Id` is present, attaches per-request inspector metadata on `req` so
+ * {@link registerCatPipeline} can re-enter `runWithInspectorBroadcastTarget` for each
+ * wrapped handler (survives deferred `next()` and async gaps). Does not wrap `next()` in ALS.
+ */
+export declare function createInspectorCorrelationMiddleware(): RequestHandler;
+//# sourceMappingURL=express-inspector-correlation.d.ts.map

package/dist/express-inspector-correlation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"express-inspector-correlation.d.ts","sourceRoot":"","sources":["../src/express-inspector-correlation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAW,cAAc,EAAE,MAAM,SAAS,CAAA;AAItD,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,qBAAqB,CAAA;AAGnE;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,eAA4C,CAAA;AAE5E,MAAM,MAAM,wBAAwB,GAAG;IACtC,QAAQ,EAAE,MAAM,CAAA;IAChB,aAAa,EAAE,MAAM,CAAA;IACrB,MAAM,EAAE,OAAO,CAAC,wBAAwB,EAAE,MAAM,CAAC,CAAA;CACjD,CAAA;AAED,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,wBAAwB,GAAG,IAAI,CAOzF;AAED,8EAA8E;AAC9E,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,OAAO,GAAG,wBAAwB,GAAG,SAAS,CAUxF;AAED;;;;GAIG;AACH,wBAAgB,oCAAoC,IAAI,cAAc,CAWrE"}

package/dist/express-inspector-correlation.js

@@ -0,0 +1,50 @@
+import { randomUUID } from 'node:crypto';
+import { readInspectorSocketIdFromHeaders } from './registry-state.js';
+/**
+ * Non-enumerable request metadata so HTTP inspector broadcasts stay correlated when
+ * middleware defers `next()` (multipart parsers, microtasks, etc.) and AsyncLocalStorage
+ * from an outer scope is no longer active.
+ */
+export const INSPECTOR_HTTP_META = Symbol.for('@gloocan/cat-inspector-http');
+export function attachInspectorHttpMeta(req, meta) {
+    Object.defineProperty(req, INSPECTOR_HTTP_META, {
+        value: meta,
+        enumerable: false,
+        writable: true,
+        configurable: true,
+    });
+}
+/** Read metadata attached by {@link createInspectorCorrelationMiddleware}. */
+export function readInspectorHttpMeta(req) {
+    if (!req || typeof req !== 'object')
+        return undefined;
+    const v = req[INSPECTOR_HTTP_META];
+    if (!v || typeof v !== 'object')
+        return undefined;
+    const o = v;
+    const socketId = typeof o.socketId === 'string' ? o.socketId : '';
+    const correlationId = typeof o.correlationId === 'string' ? o.correlationId : '';
+    if (!socketId.trim() || !correlationId.trim())
+        return undefined;
+    if (o.source !== 'http')
+        return undefined;
+    return { socketId, correlationId, source: 'http' };
+}
+/**
+ * When `X-Socket-Id` is present, attaches per-request inspector metadata on `req` so
+ * {@link registerCatPipeline} can re-enter `runWithInspectorBroadcastTarget` for each
+ * wrapped handler (survives deferred `next()` and async gaps). Does not wrap `next()` in ALS.
+ */
+export function createInspectorCorrelationMiddleware() {
+    return (req, _res, next) => {
+        const id = readInspectorSocketIdFromHeaders(req.headers);
+        if (!id) {
+            next();
+            return;
+        }
+        const correlationId = randomUUID();
+        attachInspectorHttpMeta(req, { socketId: id, correlationId, source: 'http' });
+        next();
+    };
+}
+//# sourceMappingURL=express-inspector-correlation.js.map

package/dist/express-inspector-correlation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"express-inspector-correlation.js","sourceRoot":"","sources":["../src/express-inspector-correlation.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAGxC,OAAO,EAAE,gCAAgC,EAAE,MAAM,qBAAqB,CAAA;AAEtE;;;;GAIG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,MAAM,CAAC,GAAG,CAAC,6BAA6B,CAAC,CAAA;AAQ5E,MAAM,UAAU,uBAAuB,CAAC,GAAW,EAAE,IAA8B;IAClF,MAAM,CAAC,cAAc,CAAC,GAAG,EAAE,mBAAmB,EAAE;QAC/C,KAAK,EAAE,IAAI;QACX,UAAU,EAAE,KAAK;QACjB,QAAQ,EAAE,IAAI;QACd,YAAY,EAAE,IAAI;KAClB,CAAC,CAAA;AACH,CAAC;AAED,8EAA8E;AAC9E,MAAM,UAAU,qBAAqB,CAAC,GAAY;IACjD,IAAI,CAAC,GAAG,IAAI,OAAO,GAAG,KAAK,QAAQ;QAAE,OAAO,SAAS,CAAA;IACrD,MAAM,CAAC,GAAI,GAA+B,CAAC,mBAAmB,CAAC,CAAA;IAC/D,IAAI,CAAC,CAAC,IAAI,OAAO,CAAC,KAAK,QAAQ;QAAE,OAAO,SAAS,CAAA;IACjD,MAAM,CAAC,GAAG,CAA4B,CAAA;IACtC,MAAM,QAAQ,GAAG,OAAO,CAAC,CAAC,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAA;IACjE,MAAM,aAAa,GAAG,OAAO,CAAC,CAAC,aAAa,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,EAAE,CAAA;IAChF,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,aAAa,CAAC,IAAI,EAAE;QAAE,OAAO,SAAS,CAAA;IAC/D,IAAI,CAAC,CAAC,MAAM,KAAK,MAAM;QAAE,OAAO,SAAS,CAAA;IACzC,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,EAAE,CAAA;AACnD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,oCAAoC;IACnD,OAAO,CAAC,GAAY,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE;QACnC,MAAM,EAAE,GAAG,gCAAgC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAA;QACxD,IAAI,CAAC,EAAE,EAAE,CAAC;YACT,IAAI,EAAE,CAAA;YACN,OAAM;QACP,CAAC;QACD,MAAM,aAAa,GAAG,UAAU,EAAE,CAAA;QAClC,uBAAuB,CAAC,GAAG,EAAE,EAAE,QAAQ,EAAE,EAAE,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,CAAA;QAC7E,IAAI,EAAE,CAAA;IACP,CAAC,CAAA;AACF,CAAC"}

package/dist/express-playground-mocks.d.ts

@@ -0,0 +1,28 @@
+import type { NextFunction, Request, Response } from 'express';
+export type ExpressPlaygroundPayload = {
+    headers?: Record<string, string>;
+    body?: unknown;
+    method?: string;
+    path?: string;
+    /** Optional: attach a single file (multer-like) */
+    file?: unknown;
+    /** Optional: attach multiple files by field name (multer-like) */
+    files?: unknown;
+};
+export type ExpressPlaygroundCapture = {
+    statusCode: number | null;
+    body: unknown;
+    nextCalled: boolean;
+    nextError: unknown | null;
+};
+/**
+ * Minimal req/res/next for exercising Cat Express handlers over Socket.IO.
+ * Headers should use lower-case keys where possible (Express normalizes).
+ */
+export declare function createExpressPlaygroundMocks(payload: ExpressPlaygroundPayload): {
+    req: Request;
+    res: Response;
+    next: NextFunction;
+    getCapture: () => ExpressPlaygroundCapture;
+};
+//# sourceMappingURL=express-playground-mocks.d.ts.map

package/dist/express-playground-mocks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"express-playground-mocks.d.ts","sourceRoot":"","sources":["../src/express-playground-mocks.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAA;AAE9D,MAAM,MAAM,wBAAwB,GAAG;IACtC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAChC,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,mDAAmD;IACnD,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,kEAAkE;IAClE,KAAK,CAAC,EAAE,OAAO,CAAA;CACf,CAAA;AAED,MAAM,MAAM,wBAAwB,GAAG;IACtC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;IACzB,IAAI,EAAE,OAAO,CAAA;IACb,UAAU,EAAE,OAAO,CAAA;IACnB,SAAS,EAAE,OAAO,GAAG,IAAI,CAAA;CACzB,CAAA;AAED;;;GAGG;AACH,wBAAgB,4BAA4B,CAC3C,OAAO,EAAE,wBAAwB,GAC/B;IACF,GAAG,EAAE,OAAO,CAAA;IACZ,GAAG,EAAE,QAAQ,CAAA;IACb,IAAI,EAAE,YAAY,CAAA;IAClB,UAAU,EAAE,MAAM,wBAAwB,CAAA;CAC1C,CAsDA"}

package/dist/express-playground-mocks.js

@@ -0,0 +1,55 @@
+/**
+ * Minimal req/res/next for exercising Cat Express handlers over Socket.IO.
+ * Headers should use lower-case keys where possible (Express normalizes).
+ */
+export function createExpressPlaygroundMocks(payload) {
+    const headers = {};
+    for (const [k, v] of Object.entries(payload.headers ?? {})) {
+        headers[k.toLowerCase()] = String(v);
+    }
+    let statusCode = null;
+    let body = undefined;
+    const res = {
+        status(code) {
+            statusCode = code;
+            return res;
+        },
+        json(obj) {
+            body = obj;
+            return res;
+        },
+        send(data) {
+            body = data;
+            return res;
+        },
+    };
+    let nextCalled = false;
+    let nextError = null;
+    const next = ((err) => {
+        nextCalled = true;
+        nextError = err === undefined ? null : err;
+    });
+    const req = {
+        headers,
+        body: payload.body,
+        file: payload.file,
+        files: payload.files,
+        method: payload.method ?? 'POST',
+        path: payload.path ?? '/api/run',
+        header(name) {
+            return headers[name.toLowerCase()];
+        },
+    };
+    return {
+        req,
+        res,
+        next,
+        getCapture: () => ({
+            statusCode,
+            body,
+            nextCalled,
+            nextError,
+        }),
+    };
+}
+//# sourceMappingURL=express-playground-mocks.js.map

package/dist/express-playground-mocks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"express-playground-mocks.js","sourceRoot":"","sources":["../src/express-playground-mocks.ts"],"names":[],"mappings":"AAoBA;;;GAGG;AACH,MAAM,UAAU,4BAA4B,CAC3C,OAAiC;IAOjC,MAAM,OAAO,GAA2B,EAAE,CAAA;IAC1C,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,OAAO,IAAI,EAAE,CAAC,EAAE,CAAC;QAC5D,OAAO,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,CAAA;IACrC,CAAC;IAED,IAAI,UAAU,GAAkB,IAAI,CAAA;IACpC,IAAI,IAAI,GAAY,SAAS,CAAA;IAE7B,MAAM,GAAG,GAAG;QACX,MAAM,CAAC,IAAY;YAClB,UAAU,GAAG,IAAI,CAAA;YACjB,OAAO,GAAG,CAAA;QACX,CAAC;QACD,IAAI,CAAC,GAAY;YAChB,IAAI,GAAG,GAAG,CAAA;YACV,OAAO,GAAG,CAAA;QACX,CAAC;QACD,IAAI,CAAC,IAAa;YACjB,IAAI,GAAG,IAAI,CAAA;YACX,OAAO,GAAG,CAAA;QACX,CAAC;KACsB,CAAA;IAExB,IAAI,UAAU,GAAG,KAAK,CAAA;IACtB,IAAI,SAAS,GAAY,IAAI,CAAA;IAC7B,MAAM,IAAI,GAAG,CAAC,CAAC,GAAa,EAAE,EAAE;QAC/B,UAAU,GAAG,IAAI,CAAA;QACjB,SAAS,GAAG,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAA;IAC3C,CAAC,CAAiB,CAAA;IAElB,MAAM,GAAG,GAAG;QACX,OAAO;QACP,IAAI,EAAE,OAAO,CAAC,IAAI;QAClB,IAAI,EAAE,OAAO,CAAC,IAAI;QAClB,KAAK,EAAE,OAAO,CAAC,KAAK;QACpB,MAAM,EAAE,OAAO,CAAC,MAAM,IAAI,MAAM;QAChC,IAAI,EAAE,OAAO,CAAC,IAAI,IAAI,UAAU;QAChC,MAAM,CAAC,IAAY;YAClB,OAAO,OAAO,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,CAAA;QACnC,CAAC;KACqB,CAAA;IAEvB,OAAO;QACN,GAAG;QACH,GAAG;QACH,IAAI;QACJ,UAAU,EAAE,GAAG,EAAE,CAAC,CAAC;YAClB,UAAU;YACV,IAAI;YACJ,UAAU;YACV,SAAS;SACT,CAAC;KACF,CAAA;AACF,CAAC"}

package/dist/express-qa-host-minio-upload.d.ts

@@ -0,0 +1,16 @@
+import { Router } from 'express';
+import type { HostMinioOptions } from './bootstrap.js';
+export { parseHostMinioEndpoint } from './upload/host-minio-client.js';
+export type CreateQaHostMinioUploadRouterOptions = {
+    maxFileBytes?: number;
+    /** POST path relative to where the router is mounted (default `/upload`). */
+    uploadPath?: string;
+    getUrlExpirySeconds?: number;
+};
+/**
+ * Express router: `POST` multipart field `file` → Minio `putObject` + `presignedGetObject` → JSON `{ getUrl }`.
+ * Mount with `app.use('/api/qa-host-media', router)` and set bootstrap `qaMediaUploadHostUploadUrl` to
+ * `http(s)://<public-host>:<port>/api/qa-host-media/upload` (match `uploadPath`).
+ */
+export declare function createQaHostMinioUploadRouter(hostMinio: HostMinioOptions, opts?: CreateQaHostMinioUploadRouterOptions): Router;
+//# sourceMappingURL=express-qa-host-minio-upload.d.ts.map

package/dist/express-qa-host-minio-upload.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"express-qa-host-minio-upload.d.ts","sourceRoot":"","sources":["../src/express-qa-host-minio-upload.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAA;AAGhC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAA;AAGtD,OAAO,EAAE,sBAAsB,EAAE,MAAM,+BAA+B,CAAA;AAEtE,MAAM,MAAM,oCAAoC,GAAG;IAClD,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,6EAA6E;IAC7E,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,mBAAmB,CAAC,EAAE,MAAM,CAAA;CAC5B,CAAA;AAED;;;;GAIG;AACH,wBAAgB,6BAA6B,CAC5C,SAAS,EAAE,gBAAgB,EAC3B,IAAI,GAAE,oCAAyC,GAC7C,MAAM,CAqDR"}

package/dist/express-qa-host-minio-upload.js

@@ -0,0 +1,56 @@
+import { randomUUID } from 'node:crypto';
+import { Router } from 'express';
+import multer from 'multer';
+import { createMinioClientFromHostMinio } from './upload/host-minio-client.js';
+export { parseHostMinioEndpoint } from './upload/host-minio-client.js';
+/**
+ * Express router: `POST` multipart field `file` → Minio `putObject` + `presignedGetObject` → JSON `{ getUrl }`.
+ * Mount with `app.use('/api/qa-host-media', router)` and set bootstrap `qaMediaUploadHostUploadUrl` to
+ * `http(s)://<public-host>:<port>/api/qa-host-media/upload` (match `uploadPath`).
+ */
+export function createQaHostMinioUploadRouter(hostMinio, opts = {}) {
+    const maxFileBytes = opts.maxFileBytes ?? 50 * 1024 * 1024;
+    const rawPath = opts.uploadPath ?? '/upload';
+    const uploadPath = rawPath.startsWith('/') ? rawPath : `/${rawPath}`;
+    const getExp = opts.getUrlExpirySeconds ?? 24 * 60 * 60;
+    const upload = multer({
+        storage: multer.memoryStorage(),
+        limits: { fileSize: maxFileBytes },
+    });
+    const router = Router();
+    router.post(uploadPath, (req, res, next) => {
+        upload.single('file')(req, res, (err) => {
+            if (err instanceof multer.MulterError &&
+                err.code === 'LIMIT_FILE_SIZE') {
+                res.status(413).json({ error: 'file too large' });
+                return;
+            }
+            next(err);
+        });
+    }, async (req, res, next) => {
+        try {
+            const file = req.file;
+            if (!file?.buffer) {
+                res.status(400).json({ error: 'missing file' });
+                return;
+            }
+            const client = createMinioClientFromHostMinio(hostMinio);
+            const objectKey = `qa/${Date.now()}-${randomUUID()}`;
+            const contentType = file.mimetype || 'application/octet-stream';
+            await client.putObject(hostMinio.bucket, objectKey, file.buffer, file.size, {
+                'Content-Type': contentType,
+            });
+            const getUrl = await client.presignedGetObject(hostMinio.bucket, objectKey, getExp);
+            res.json({ getUrl });
+        }
+        catch (e) {
+            next(e);
+        }
+    });
+    router.use((err, _req, res, _next) => {
+        const msg = err instanceof Error ? err.message : String(err);
+        res.status(503).json({ error: msg });
+    });
+    return router;
+}
+//# sourceMappingURL=express-qa-host-minio-upload.js.map

package/dist/express-qa-host-minio-upload.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"express-qa-host-minio-upload.js","sourceRoot":"","sources":["../src/express-qa-host-minio-upload.ts"],"names":[],"mappings":"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"}

package/dist/express.d.ts

@@ -0,0 +1,21 @@
+import type { Express, NextFunction, Request, Response, Router } from 'express';
+export type HttpMethod = 'get' | 'post' | 'put' | 'delete' | 'patch';
+export declare function pipelineIdForRoute(method: string, route: string): string;
+export declare function registerCatPipeline(router: Router, method: HttpMethod, route: string, handlers: readonly ((...args: any[]) => any)[]): void;
+export declare function createCorrelationMiddleware(): (req: Request, res: Response, next: NextFunction) => void;
+/**
+ * Run one in-process HTTP request against an Express `app` (local `127.0.0.1` ephemeral port).
+ * Useful for QA / tests that need real `req`/`res` middleware without deploying.
+ */
+export declare function invokeExpressSynthetic(app: Express, opts: {
+    method: HttpMethod;
+    path: string;
+    headers?: Record<string, string>;
+    body?: unknown;
+}): Promise<{
+    statusCode: number;
+    headers: Record<string, string>;
+    bodyText: string;
+    bodyJson: unknown;
+}>;
+//# sourceMappingURL=express.d.ts.map

package/dist/express.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"express.d.ts","sourceRoot":"","sources":["../src/express.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,OAAO,EAAE,YAAY,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,SAAS,CAAA;AAS/E,MAAM,MAAM,UAAU,GAAG,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,QAAQ,GAAG,OAAO,CAAA;AAEpE,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAExE;AAED,wBAAgB,mBAAmB,CAClC,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,UAAU,EAClB,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,SAAS,CAAC,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,CAAC,EAAE,GAC5C,IAAI,CA0FN;AAED,wBAAgB,2BAA2B,IAAI,CAC9C,GAAG,EAAE,OAAO,EACZ,GAAG,EAAE,QAAQ,EACb,IAAI,EAAE,YAAY,KACd,IAAI,CAmBR;AAED;;;GAGG;AACH,wBAAsB,sBAAsB,CAC3C,GAAG,EAAE,OAAO,EACZ,IAAI,EAAE;IACL,MAAM,EAAE,UAAU,CAAA;IAClB,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAChC,IAAI,CAAC,EAAE,OAAO,CAAA;CACd,GACC,OAAO,CAAC;IACV,UAAU,EAAE,MAAM,CAAA;IAClB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC/B,QAAQ,EAAE,MAAM,CAAA;IAChB,QAAQ,EAAE,OAAO,CAAA;CACjB,CAAC,CA6CD"}

package/dist/express.js

@@ -0,0 +1,167 @@
+import http from 'node:http';
+import { readInspectorHttpMeta } from './express-inspector-correlation.js';
+import { ApiContext, Registry, runWithInspectorBroadcastTarget, runWithProducerFnKey } from './registry-state.js';
+function isThenable(v) {
+    return Boolean(v && typeof v.then === 'function');
+}
+export function pipelineIdForRoute(method, route) {
+    return `${method.toUpperCase()} ${route}`;
+}
+export function registerCatPipeline(router, method, route, handlers) {
+    const pid = pipelineIdForRoute(method, route);
+    const endpointHandler = handlers[handlers.length - 1];
+    let endpointFnKey = null;
+    handlers.forEach((handler, index) => {
+        if (typeof handler !== 'function')
+            return;
+        const isLast = index === handlers.length - 1;
+        Registry.forEach((entry) => {
+            if (entry.originalFn === handler &&
+                (entry.mode === 'api_candidate' || entry.mode === 'api')) {
+                entry.route = route;
+                entry.httpMethod = method.toUpperCase();
+                entry.pipelineId = pid;
+                entry.pipelineIndex = index;
+                // In a pipeline, treat the final handler as the endpoint ("api"),
+                // and prior handlers as middleware ("api_candidate").
+                entry.mode = isLast ? 'api' : 'api_candidate';
+            }
+        });
+        if (handler === endpointHandler) {
+            for (const [k, e] of Registry.entries()) {
+                if (e.originalFn === handler) {
+                    endpointFnKey = k;
+                    break;
+                }
+            }
+        }
+    });
+    const wrapped = handlers.map((handler) => {
+        if (typeof handler !== 'function')
+            return handler;
+        let fnKey = null;
+        for (const [k, e] of Registry.entries()) {
+            if (e.originalFn === handler) {
+                fnKey = k;
+                break;
+            }
+        }
+        return function wrappedPipelineHandler(...args) {
+            const req = args[0];
+            const res = args[1];
+            const next = args[2];
+            const runInner = () => {
+                // Ensure ApiReturn broadcasts are correlated to the endpoint for HTTP requests.
+                if (endpointFnKey)
+                    ApiContext.set(endpointFnKey);
+                return runWithProducerFnKey(fnKey, () => {
+                    if (typeof next !== 'function') {
+                        // Express route handler (req,res) style
+                        return handler.apply(this, args);
+                    }
+                    const wrappedNext = (...nextArgs) => {
+                        return next(...nextArgs);
+                    };
+                    return handler.call(this, req, res, wrappedNext);
+                });
+            };
+            const runWithHttpInspector = () => {
+                const meta = req ? readInspectorHttpMeta(req) : undefined;
+                if (meta) {
+                    return runWithInspectorBroadcastTarget(meta.socketId, runInner, {
+                        source: 'http',
+                        correlationId: meta.correlationId,
+                    });
+                }
+                return runInner();
+            };
+            try {
+                const out = runWithHttpInspector();
+                if (isThenable(out)) {
+                    return Promise.resolve(out).finally(() => {
+                        ApiContext.clear();
+                    });
+                }
+                ApiContext.clear();
+                return out;
+            }
+            catch (err) {
+                ApiContext.clear();
+                throw err;
+            }
+        };
+    });
+    router[method](route, ...wrapped);
+}
+export function createCorrelationMiddleware() {
+    return function correlationMiddleware(req, res, next) {
+        const header = req.header('x-correlation-id') ?? req.header('x-request-id') ?? undefined;
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const r = req;
+        if (r.correlationId === undefined)
+            r.correlationId = header ?? `${Date.now()}`;
+        if (!res.headersSent) {
+            try {
+                res.setHeader('X-Correlation-Id', String(r.correlationId));
+            }
+            catch {
+                // ignore
+            }
+        }
+        next();
+    };
+}
+/**
+ * Run one in-process HTTP request against an Express `app` (local `127.0.0.1` ephemeral port).
+ * Useful for QA / tests that need real `req`/`res` middleware without deploying.
+ */
+export async function invokeExpressSynthetic(app, opts) {
+    const server = http.createServer(app);
+    await new Promise((resolve, reject) => {
+        server.once('error', reject);
+        server.listen(0, '127.0.0.1', () => resolve());
+    });
+    const addr = server.address();
+    const port = addr.port;
+    const path = opts.path.startsWith('/') ? opts.path : `/${opts.path}`;
+    const url = `http://127.0.0.1:${port}${path}`;
+    try {
+        const method = opts.method.toUpperCase();
+        const headers = new Headers();
+        for (const [k, v] of Object.entries(opts.headers ?? {})) {
+            headers.set(k, v);
+        }
+        const init = { method, headers };
+        if (opts.body !== undefined && method !== 'GET' && method !== 'HEAD') {
+            if (!headers.has('content-type')) {
+                headers.set('content-type', 'application/json');
+            }
+            init.body = JSON.stringify(opts.body);
+        }
+        const resp = await fetch(url, init);
+        const bodyText = await resp.text();
+        let bodyJson = bodyText;
+        if (bodyText) {
+            try {
+                bodyJson = JSON.parse(bodyText);
+            }
+            catch {
+                bodyJson = bodyText;
+            }
+        }
+        else {
+            bodyJson = null;
+        }
+        const outHeaders = {};
+        resp.headers.forEach((v, k) => {
+            outHeaders[k] = v;
+        });
+        return { statusCode: resp.status, headers: outHeaders, bodyText, bodyJson };
+    }
+    finally {
+        await new Promise((resolve, reject) => {
+            server.close((err) => (err ? reject(err) : resolve()));
+        });
+    }
+}
+//# sourceMappingURL=express.js.map

package/dist/express.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"express.js","sourceRoot":"","sources":["../src/express.ts"],"names":[],"mappings":"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"}

package/dist/functional.d.ts

@@ -0,0 +1,15 @@
+export interface CatFunctionOptions {
+    method?: string;
+    route?: string;
+    /**
+     * Optional manual type hints (fallback when AST scan isn't run).
+     * If provided, overrides default 'unknown' registration types.
+     */
+    params?: import('./types.js').RegistryParam[];
+    declaredReturn?: string;
+    /** Optional JSON Schema (draft-07 subset) for the entire positional args array when `validateParamsJsonSchema` is enabled. */
+    paramsJsonSchema?: Record<string, unknown>;
+}
+export declare function cat<T extends (...args: any[]) => any>(fnKey: string, fn: T, options?: CatFunctionOptions): T;
+export declare function catModule<T extends Record<string, (...args: any[]) => any>>(moduleName: string, fns: T, options?: Record<string, Pick<CatFunctionOptions, 'params' | 'declaredReturn' | 'paramsJsonSchema'>>): T;
+//# sourceMappingURL=functional.d.ts.map

package/dist/functional.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"functional.d.ts","sourceRoot":"","sources":["../src/functional.ts"],"names":[],"mappings":"AAiBA,MAAM,WAAW,kBAAkB;IAClC,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,KAAK,CAAC,EAAE,MAAM,CAAA;IACd;;;OAGG;IACH,MAAM,CAAC,EAAE,OAAO,YAAY,EAAE,aAAa,EAAE,CAAA;IAC7C,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,8HAA8H;IAC9H,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAC1C;AAyID,wBAAgB,GAAG,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,EACpD,KAAK,EAAE,MAAM,EACb,EAAE,EAAE,CAAC,EACL,OAAO,CAAC,EAAE,kBAAkB,GAC1B,CAAC,CA6BH;AAED,wBAAgB,SAAS,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,CAAC,EAC1E,UAAU,EAAE,MAAM,EAClB,GAAG,EAAE,CAAC,EACN,OAAO,CAAC,EAAE,MAAM,CACf,MAAM,EACN,IAAI,CAAC,kBAAkB,EAAE,QAAQ,GAAG,gBAAgB,GAAG,kBAAkB,CAAC,CAC1E,GACC,CAAC,CA6BH"}