@karmaniverous/smoz 0.1.2

package/dist/mjs/index.js

@@ -0,0 +1,690 @@
+import { dirname, relative, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { baseEventTypeMapSchema as baseEventTypeMapSchema$1 } from '@/src/core/baseEventTypeMapSchema';
+import { buildStageArtifacts } from '@/src/core/buildStageArtifacts';
+import { validateEventTypeMapSchemaIncludesBase, defaultHttpEventTypeTokens } from '@/src/core/httpTokens';
+import { createRegistry } from '@/src/core/registry';
+import { serverlessConfigSchema } from '@/src/core/serverlessConfig';
+import { buildAllOpenApiPaths } from '@/src/openapi/buildOpenApi';
+import { buildAllServerlessFunctions } from '@/src/serverless/buildServerless';
+import { z } from 'zod';
+import { stagesFactory } from '@/src/serverless/stagesFactory';
+import middy from '@middy/core';
+import { getEnvFromFunctionConfig } from '@/src/core/defineFunctionConfig';
+import { computeHttpMiddleware } from '@/src/http/middleware/httpStackCustomization';
+import { deriveAllKeys, splitKeysBySchema, buildEnvSchema, parseTypedEnv } from '@/src/runtime/envBuilder';
+import '@/src/http/middleware/combine';
+import { tagStep as tagStep$1 } from '@/src/http/middleware/transformUtils';
+import httpContentNegotiation from '@middy/http-content-negotiation';
+import httpCors from '@middy/http-cors';
+import httpErrorHandler from '@middy/http-error-handler';
+import httpEventNormalizer from '@middy/http-event-normalizer';
+import httpHeaderNormalizer from '@middy/http-header-normalizer';
+import httpJsonBodyParser from '@middy/http-json-body-parser';
+import httpResponseSerializer from '@middy/http-response-serializer';
+import { asApiMiddleware } from '@/src/http/middleware/asApiMiddleware';
+import { httpZodValidator } from '@/src/http/middleware/httpZodValidator';
+import { shortCircuitHead } from '@/src/http/middleware/shortCircuitHead';
+import { wrapSerializer } from '@/src/http/middleware/wrapSerializer';
+
+/**
+ * App (schema‑first)
+ *
+ * Central orchestrator for a SMOZ application. You provide:
+ * - Global/stage parameter schemas and env exposure keys
+ * - Serverless defaults (handler filename/export and context map)
+ * - Event‑type map schema (extendable: e.g., add 'step')
+ *
+ * The instance:
+ * - Validates configuration
+ * - Exposes env and stage artifacts for Serverless (provider.environment and params)
+ * - Provides a registry to define functions (HTTP and non‑HTTP)
+ * - Aggregates artifacts:
+ *   - buildAllServerlessFunctions(): AWS['functions']
+ *   - buildAllOpenApiPaths(): ZodOpenApiPathsObject
+ *
+ * @remarks See README for a full quick‑start, and typedoc for detailed API docs.
+ */
+/**
+ * Application class. *
+ * @typeParam GlobalParamsSchema - Zod object schema for global parameters
+ * @typeParam StageParamsSchema  - Zod object schema for per‑stage parameters
+ * @typeParam EventTypeMapSchema - Zod object schema mapping event tokens to runtime types
+ */ class App {
+    /** Helper alias for stage artifacts type */
+    static _stageArtifactsType = null;
+    appRootAbs;
+    // Schemas
+    globalParamsSchema;
+    stageParamsSchema;
+    eventTypeMapSchema; // Serverless config
+    serverless;
+    // Env exposure
+    global;
+    stage;
+    // Derived stage artifacts
+    stages;
+    environment;
+    buildFnEnv;
+    http;
+    // HTTP tokens for runtime decision
+    httpEventTypeTokens;
+    // Registry (delegated to src/app/registry)
+    registry;
+    constructor(init) {
+        this.appRootAbs = init.appRootAbs.replace(/\\/g, '/');
+        this.globalParamsSchema = init.globalParamsSchema;
+        this.stageParamsSchema = init.stageParamsSchema;
+        // Default to base schema when omitted (apply default INSIDE the function)
+        this.eventTypeMapSchema = (init.eventTypeMapSchema ??
+            baseEventTypeMapSchema$1);
+        // Parse serverless input internally
+        this.serverless = serverlessConfigSchema.parse(init.serverless);
+        // Validate that eventTypeMapSchema includes base keys at runtime
+        validateEventTypeMapSchemaIncludesBase(this.eventTypeMapSchema.shape);
+        // Env exposure nodes
+        this.global = {
+            paramsSchema: this.globalParamsSchema,
+            envKeys: init.global.envKeys,
+        };
+        this.stage = {
+            paramsSchema: this.stageParamsSchema,
+            envKeys: init.stage.envKeys,
+        };
+        // Build stages/environment/fn-env via helper (applies “stage extends global” and parsing)
+        const { stages, environment, buildFnEnv } = buildStageArtifacts(this.globalParamsSchema, this.stageParamsSchema, { params: init.global.params, envKeys: init.global.envKeys }, { params: init.stage.params, envKeys: init.stage.envKeys });
+        this.stages = stages;
+        this.environment = environment;
+        this.buildFnEnv = buildFnEnv;
+        // HTTP tokens (runtime decision)
+        this.httpEventTypeTokens = (init.httpEventTypeTokens ??
+            defaultHttpEventTypeTokens);
+        // App-level HTTP customization
+        this.http = init.http ?? {};
+        // Initialize function registry
+        this.registry = createRegistry({
+            httpEventTypeTokens: this.httpEventTypeTokens,
+            env: { global: this.global, stage: this.stage },
+            http: this.http,
+            // With exactOptionalPropertyTypes, do not pass an explicit undefined.
+            ...(init.functionDefaults
+                ? { functionDefaults: init.functionDefaults }
+                : {}),
+        });
+    } /**
+     * Ergonomic constructor for schema‑first inference.
+     *
+     * @param init - initialization object (schemas, serverless defaults, params/envKeys)
+     * @returns a new App instance
+     */
+    static create(init) {
+        return new App(init);
+    }
+    /**
+     * Register a function (HTTP or non‑HTTP).
+     *
+     * @typeParam EventType      - A key from your eventTypeMapSchema (e.g., 'rest' | 'http' | 'sqs' | 'step')
+     * @typeParam EventSchema    - Optional Zod schema validated BEFORE the handler (refines event shape)
+     * @typeParam ResponseSchema - Optional Zod schema validated AFTER the handler (refines response shape)
+     * @param options - per‑function configuration (method/basePath/httpContexts for HTTP; serverless extras for non‑HTTP)
+     * @returns a per‑function API: { handler(business), openapi(baseOperation), serverless(extras) }
+     */
+    defineFunction(options) {
+        const functionName = options.functionName ??
+            (() => {
+                const callerDir = dirname(fileURLToPath(options.callerModuleUrl));
+                const rel = relative(this.appRootAbs, callerDir).split(sep).join('/');
+                const parts = rel.split('/').filter(Boolean);
+                // Drop leading 'app' segment if present, per repo convention
+                if (parts[0] === 'app')
+                    parts.shift();
+                return parts.join('_'); // underscore formatting
+            })();
+        return this.registry.defineFunction({
+            functionName,
+            eventType: options.eventType,
+            ...(options.method ? { method: options.method } : {}),
+            ...(options.basePath ? { basePath: options.basePath } : {}),
+            ...(options.httpContexts ? { httpContexts: options.httpContexts } : {}),
+            ...(options.contentType ? { contentType: options.contentType } : {}),
+            ...(options.eventSchema ? { eventSchema: options.eventSchema } : {}),
+            ...(options.responseSchema
+                ? { responseSchema: options.responseSchema }
+                : {}),
+            ...(options.fnEnvKeys ? { fnEnvKeys: options.fnEnvKeys } : {}),
+            callerModuleUrl: options.callerModuleUrl,
+            endpointsRootAbs: options.endpointsRootAbs,
+        });
+    }
+    /**
+     * Aggregate Serverless function definitions across the registry.
+     *
+     * @returns An AWS['functions'] object suitable for serverless.ts
+     */
+    buildAllServerlessFunctions() {
+        return buildAllServerlessFunctions(this.registry.values(), this.serverless, this.buildFnEnv);
+    }
+    /**
+     * Aggregate OpenAPI path items across the registry.
+     *
+     * @returns ZodOpenApiPathsObject to be embedded in a full OpenAPI document
+     */
+    buildAllOpenApiPaths() {
+        return buildAllOpenApiPaths(this.registry.values());
+    }
+}
+
+const baseEventTypeMapSchema = z.object({
+    rest: z.custom(),
+    http: z.custom(),
+    alb: z.custom(),
+    sqs: z.custom(),
+    sns: z.custom(),
+    s3: z.custom(),
+    dynamodb: z.custom(),
+    kinesis: z.custom(),
+    eventbridge: z.custom(),
+    'cloudwatch-logs': z.custom(),
+    ses: z.custom(),
+    cloudfront: z.custom(),
+    firehose: z.custom(),
+    // eslint-disable-next-line @typescript-eslint/no-deprecated -- Upstream AWS types mark this as deprecated; we retain the token for compatibility with existing apps.
+    'cognito-userpool': z.custom(),
+});
+// Notes:
+// - This list intentionally includes widely used, generic AWS events.
+// - Apps can extend the schema with custom or specialized tokens:
+//     const EventMap = baseEventTypeMapSchema.extend({ step: z.custom<MyStepEvent>() })
+// - Only tokens listed in your App's httpEventTypeTokens are treated as HTTP by the runtime.
+
+/**
+ * Define a complete application configuration from schemas and authoring input.
+ *
+ * @typeParam GlobalParamsSchema - Global params schema
+ * @typeParam StageParamsSchema  - Per‑stage params schema
+ * @param globalParamsSchema - schema for global params
+ * @param stageParamsSchema  - schema for stage params
+ * @param input - serverless defaults and concrete params + env exposure
+ * @returns Typed configuration nodes and stage artifacts
+ * * @throws Error if envKeys include keys not present in their corresponding schema
+ */
+function defineAppConfig(globalParamsSchema, stageParamsSchema, input) {
+    const assertKeysSubset = (schema, keys, label) => {
+        const allowed = new Set(Object.keys(schema.shape));
+        const bad = keys.filter((k) => !allowed.has(k));
+        if (bad.length)
+            throw new Error(`${label} contains unknown keys: ${bad.join(', ')}`);
+    };
+    assertKeysSubset(globalParamsSchema, input.global.envKeys, 'global.envKeys');
+    assertKeysSubset(stageParamsSchema, input.stage.envKeys, 'stage.envKeys');
+    const sf = stagesFactory({
+        globalParamsSchema,
+        stageParamsSchema,
+        globalParams: input.global.params,
+        globalEnvKeys: input.global.envKeys,
+        stageEnvKeys: input.stage.envKeys,
+        stages: input.stage.params,
+    });
+    return {
+        serverless: input.serverless,
+        global: { paramsSchema: globalParamsSchema, envKeys: input.global.envKeys },
+        stage: { paramsSchema: stageParamsSchema, envKeys: input.stage.envKeys },
+        stages: sf.stages,
+        environment: sf.environment,
+        buildFnEnv: sf.buildFnEnv,
+    };
+}
+
+/** Narrow to API Gateway v1 events with safe property checks. */
+/**
+ * Type guard for API Gateway v1 events. *
+ * @param evt - unknown event
+ * @returns true if the event looks like a v1 APIGatewayProxyEvent
+ */
+const isV1 = (evt) => {
+    if (typeof evt !== 'object' || evt === null)
+        return false;
+    return 'httpMethod' in evt && 'requestContext' in evt;
+};
+/** Narrow to API Gateway v2 events with safe property checks. */
+/**
+ * Type guard for API Gateway v2 events.
+ */
+const isV2 = (evt) => {
+    if (typeof evt !== 'object' || evt === null)
+        return false;
+    if (!('version' in evt) || !('requestContext' in evt))
+        return false;
+    const rc = evt.requestContext;
+    return (!!rc && typeof rc === 'object' && 'http' in rc);
+};
+/** Case-insensitive single-value header lookup. */
+const getHeader = (headers, key) => {
+    if (!headers)
+        return undefined;
+    const direct = headers[key];
+    if (typeof direct === 'string')
+        return direct;
+    const found = Object.keys(headers).find((k) => k.toLowerCase() === key.toLowerCase());
+    return found ? headers[found] : undefined;
+};
+/** Case-insensitive multi-value header lookup. */
+const getMultiHeader = (headers, key) => {
+    if (!headers)
+        return undefined;
+    const direct = headers[key];
+    if (Array.isArray(direct) && direct.length > 0)
+        return direct[0];
+    const found = Object.keys(headers).find((k) => k.toLowerCase() === key.toLowerCase());
+    return found ? headers[found]?.[0] : undefined;
+};
+/** Get a header value from either single- or multi-value maps. */
+const getHeaderFromEvent = (evt, key) => {
+    const single = getHeader(evt.headers, key);
+    if (typeof single === 'string')
+        return single;
+    const multi = getMultiHeader(evt
+        .multiValueHeaders, key);
+    return multi;
+};
+const hasAwsSig = (auth) => typeof auth === 'string' && auth.startsWith('AWS4-HMAC-SHA256');
+const hasV1AccessKey = (evt) => {
+    const rc = evt.requestContext;
+    const ak = rc.identity?.accessKey;
+    return typeof ak === 'string' && ak.length > 0;
+};
+const hasAuthorizer = (evt) => {
+    // V1: any truthy authorizer object indicates an authenticated request
+    if (isV1(evt)) {
+        const rc = evt.requestContext;
+        return !!rc.authorizer;
+    }
+    // V2: authorizer may include jwt/iam/lambda shapes
+    const authHeader = getHeaderFromEvent(evt, 'authorization');
+    if (hasAwsSig(authHeader))
+        return true;
+    const rc = evt
+        .requestContext;
+    const { authorizer } = rc;
+    if (!authorizer || typeof authorizer !== 'object')
+        return false;
+    const a = authorizer;
+    return !!(a.jwt || a.iam || a.lambda);
+};
+/** Detect API key via header or v1 identity.apiKey. */
+const hasApiKey = (evt) => {
+    const fromHeader = getHeaderFromEvent(evt, 'x-api-key');
+    if (typeof fromHeader === 'string')
+        return true;
+    // Some v1 events surface API key on requestContext.identity.apiKey
+    if (isV1(evt)) {
+        const rc = evt.requestContext;
+        const identKey = rc.identity?.apiKey;
+        if (typeof identKey === 'string' && identKey.length > 0)
+            return true;
+        const identKeyId = rc.identity?.apiKeyId;
+        if (typeof identKeyId === 'string' && identKeyId.length > 0)
+            return true;
+    }
+    return false;
+};
+/** Classify the security context from either API Gateway event version. */
+/**
+ * Detect security context from API Gateway v1/v2 events.
+ *
+ * @param evt - unknown event
+ * @returns 'my' when authorized (Cognito/JWT/IAM), 'private' when API key present, else 'public'
+ */
+const detectSecurityContext = (evt) => {
+    if (isV1(evt)) {
+        const auth = getHeaderFromEvent(evt, 'authorization');
+        if (hasAwsSig(auth) || hasV1AccessKey(evt) || hasAuthorizer(evt))
+            return 'my';
+        if (hasApiKey(evt))
+            return 'private';
+        return 'public';
+    }
+    if (isV2(evt)) {
+        const auth = getHeaderFromEvent(evt, 'authorization');
+        if (hasAwsSig(auth) || hasAuthorizer(evt))
+            return 'my';
+        if (hasApiKey(evt))
+            return 'private';
+        return 'public';
+    }
+    return 'public';
+};
+
+/**
+ * Wrap a business handler with SMOZ runtime. *
+ * - HTTP event tokens receive the full Middy pipeline (validation, shaping, CORS, etc.)
+ * - Non‑HTTP tokens bypass Middy and call the business function directly.
+ *
+ * @typeParam GlobalParamsSchema - global params schema type
+ * @typeParam StageParamsSchema  - stage params schema type
+ * @typeParam EventTypeMap       - event token → runtime type map
+ * @typeParam EventType          - a key of EventTypeMap
+ * @typeParam EventSchema        - optional Zod schema for event (validated before handler)
+ * @typeParam ResponseSchema     - optional Zod schema for response (validated after handler)
+ * @param functionConfig - per‑function configuration (branded with env nodes)
+ * @param business - the business handler implementation
+ * @param opts - optional runtime overrides (e.g., widen HTTP tokens)
+ * @returns a Lambda‑compatible handler function
+ */
+function wrapHandler(functionConfig, business, opts) {
+    const assertKeysSubset = (schema, keys, label) => {
+        const allowed = new Set(Object.keys(schema.shape));
+        const bad = keys.filter((k) => !allowed.has(k));
+        if (bad.length)
+            throw new Error(`${label} contains unknown keys: ${bad.join(', ')}`);
+    };
+    const envConfig = getEnvFromFunctionConfig(functionConfig);
+    assertKeysSubset(envConfig.global.paramsSchema, envConfig.global.envKeys, 'global.envKeys');
+    assertKeysSubset(envConfig.stage.paramsSchema, envConfig.stage.envKeys, 'stage.envKeys');
+    return async (event, context) => {
+        // Compose typed env schema and parse process.env
+        const all = deriveAllKeys(envConfig.global.envKeys, envConfig.stage.envKeys, (functionConfig.fnEnvKeys ?? []));
+        const { globalPick, stagePick } = splitKeysBySchema(all, envConfig.global.paramsSchema, envConfig.stage.paramsSchema);
+        const envSchema = buildEnvSchema(globalPick, stagePick, envConfig.global.paramsSchema, envConfig.stage.paramsSchema);
+        const env = parseTypedEnv(envSchema, process.env);
+        const logger = console;
+        // Non-HTTP: call business directly
+        const httpTokens = opts?.httpEventTypeTokens ??
+            defaultHttpEventTypeTokens;
+        const isHttp = httpTokens.includes(functionConfig.eventType);
+        if (!isHttp) {
+            return business(event, context, { env, logger });
+        }
+        // HTTP: build middleware stack
+        const fnHttp = functionConfig.http;
+        const maybeContentType = functionConfig
+            .contentType;
+        const args = {
+            functionName: functionConfig.functionName,
+            logger,
+            ...(functionConfig.eventSchema
+                ? { eventSchema: functionConfig.eventSchema }
+                : {}),
+            ...(functionConfig.responseSchema
+                ? { responseSchema: functionConfig.responseSchema }
+                : {}),
+            ...(typeof maybeContentType === 'string' && maybeContentType.length > 0
+                ? { contentType: maybeContentType }
+                : {}),
+            ...(opts?.httpConfig ? { app: opts.httpConfig } : {}),
+            ...(fnHttp ? { fn: fnHttp } : {}),
+        };
+        const http = computeHttpMiddleware(args);
+        const wrapped = middy(async (e, c) => business(e, c, {
+            env,
+            logger,
+        })).use(http);
+        return wrapped(event, context);
+    };
+}
+
+const makeHead = () => tagStep$1(shortCircuitHead, 'head');
+const makeHeaderNormalizer = (opts) => tagStep$1(asApiMiddleware(httpHeaderNormalizer(opts?.headerNormalizer ?? { canonical: true })), 'header-normalizer');
+const makeEventNormalizer = () => tagStep$1(asApiMiddleware(httpEventNormalizer()), 'event-normalizer');
+const makeContentNegotiation = (contentType, opts) => {
+    const availableMediaTypes = [contentType];
+    const merged = {
+        parseLanguages: false,
+        parseCharsets: false,
+        parseEncodings: false,
+        availableMediaTypes,
+        ...(opts?.contentNegotiation ?? {}),
+    };
+    return tagStep$1(asApiMiddleware(httpContentNegotiation(merged)), 'content-negotiation');
+};
+const makeJsonBodyParser = (opts) => {
+    const inner = asApiMiddleware(httpJsonBodyParser({
+        disableContentTypeError: true,
+        ...(opts?.jsonBodyParser ?? {}),
+    }));
+    const mw = {};
+    mw.before = async (request) => {
+        const event = request
+            .event;
+        if (!event)
+            return;
+        const method = (event.httpMethod ||
+            event
+                .requestContext?.http?.method ||
+            '').toUpperCase();
+        if (method === 'GET' || method === 'HEAD')
+            return;
+        if (!event.body)
+            return;
+        if (inner.before)
+            await inner.before(request);
+    };
+    return tagStep$1(mw, 'json-body-parser');
+};
+const makeZodBefore = (logger, eventSchema) => {
+    const base = httpZodValidator({
+        logger,
+        ...(eventSchema ? { eventSchema } : {}),
+    });
+    const mw = {};
+    if (base.before)
+        mw.before = base.before;
+    return tagStep$1(mw, 'zod-before');
+};
+const makeZodAfter = (logger, responseSchema) => {
+    const base = httpZodValidator({
+        logger,
+        ...(responseSchema ? { responseSchema } : {}),
+    });
+    const mw = {};
+    if (base.after)
+        mw.after = base.after;
+    return tagStep$1(mw, 'zod-after');
+};
+const makeHeadFinalize = (contentType) => tagStep$1({
+    after: (request) => {
+        const evt = request
+            .event;
+        if (!evt)
+            return;
+        const method = (evt.httpMethod ||
+            evt.requestContext?.http?.method ||
+            '').toUpperCase();
+        if (method !== 'HEAD')
+            return;
+        request.response = {
+            statusCode: 200,
+            headers: { 'Content-Type': contentType },
+            body: {},
+        };
+    },
+}, 'head-finalize');
+const makePreferredMedia = (contentType) => tagStep$1({
+    before: (request) => {
+        const req = request;
+        if (!Array.isArray(req.preferredMediaTypes))
+            req.preferredMediaTypes = [contentType];
+        const ri = request;
+        if (!ri.internal)
+            ri.internal = {};
+        const internal = ri.internal;
+        if (!Array.isArray(internal.preferredMediaTypes))
+            internal.preferredMediaTypes = [contentType];
+    },
+    after: (request) => {
+        const req = request;
+        if (!Array.isArray(req.preferredMediaTypes))
+            req.preferredMediaTypes = [contentType];
+    },
+    onError: (request) => {
+        const req = request;
+        if (!Array.isArray(req.preferredMediaTypes))
+            req.preferredMediaTypes = [contentType];
+    },
+}, 'preferred-media');
+const makeErrorExpose = (logger) => tagStep$1({
+    onError: (request) => {
+        const maybe = request.error;
+        if (!(maybe instanceof Error))
+            return;
+        const msg = typeof maybe.message === 'string' ? maybe.message : '';
+        maybe.expose = true;
+        if (typeof maybe.statusCode !== 'number' &&
+            ((typeof maybe.name === 'string' &&
+                maybe.name.toLowerCase().includes('zod')) ||
+                /invalid (event|response)/i.test(msg))) {
+            maybe.statusCode = 400;
+        }
+    },
+}, 'error-expose');
+const makeErrorHandler = (opts) => tagStep$1(asApiMiddleware(httpErrorHandler({
+    ...(opts?.errorHandler ?? {}),
+    logger: (o) => {
+        const lg = opts?.logger ?? console;
+        if (typeof lg.error === 'function')
+            lg.error(o);
+    },
+})), 'error-handler');
+const makeCors = (opts) => tagStep$1(asApiMiddleware(httpCors({
+    credentials: true,
+    getOrigin: (o) => o,
+    ...(opts?.cors ?? {}),
+})), 'cors');
+const makeShapeAndContentType = (contentType) => tagStep$1({
+    after: (request) => {
+        const container = request;
+        const current = container.response;
+        if (current === undefined)
+            return;
+        const looksShaped = typeof current === 'object' &&
+            current !== null &&
+            'statusCode' in current &&
+            'headers' in current &&
+            'body' in current;
+        let res;
+        if (looksShaped)
+            res = current;
+        else
+            res = { statusCode: 200, headers: {}, body: current };
+        if (res.body !== undefined && typeof res.body !== 'string') {
+            try {
+                res.body = JSON.stringify(res.body);
+            }
+            catch {
+                res.body = String(res.body);
+            }
+        }
+        const headers = res.headers ?? {};
+        headers['Content-Type'] = contentType;
+        res.headers = headers;
+        request.response = res;
+    },
+}, 'shape');
+const makeSerializer = (contentType, opts) => tagStep$1(asApiMiddleware(httpResponseSerializer({
+    serializers: [
+        {
+            regex: /^application\/(?:[a-z0-9.+-]*\+)?json$/i,
+            serializer: wrapSerializer(({ body }) => typeof body === 'string'
+                ? body
+                : (opts?.serializer?.json?.stringify ?? JSON.stringify)(body), {
+                label: opts?.serializer?.json?.label ?? 'json',
+                logger: opts?.logger ?? console,
+            }),
+        },
+    ],
+    defaultContentType: contentType,
+})), 'serializer');
+const buildDefaultPhases = (args) => {
+    const { contentType, logger, opts, eventSchema, responseSchema } = args;
+    const before = [
+        makeHead(),
+        makeHeaderNormalizer(opts),
+        makeEventNormalizer(),
+        makeContentNegotiation(contentType, opts),
+        makeJsonBodyParser(opts),
+        makeZodBefore(logger, eventSchema),
+    ];
+    const after = [
+        makeHeadFinalize(contentType),
+        makeZodAfter(logger, responseSchema),
+        makeErrorExpose(),
+        makeCors(opts),
+        makePreferredMedia(contentType),
+        makeShapeAndContentType(contentType),
+        makeSerializer(contentType, opts),
+    ];
+    const onError = [makeErrorExpose(), makeErrorHandler(opts)];
+    return { before, after, onError };
+};
+const buildSafeDefaults = (args) => buildDefaultPhases(args);
+
+const ID_PROP = '__id';
+/** Attach a non-enumerable __id to a middleware step. */
+const tagStep = (mw, id) => {
+    if (!Object.prototype.hasOwnProperty.call(mw, ID_PROP)) {
+        Object.defineProperty(mw, ID_PROP, { value: id, enumerable: false });
+    }
+    return mw;
+};
+/** Retrieve a step's id, if present. */
+const getId = (mw) => mw[ID_PROP];
+/** Find index of a step by id. */
+const findIndex = (list, id) => list.findIndex((m) => getId(m) === id);
+/** Insert a step before the step with given id. */
+const insertBefore = (list, id, mw) => {
+    const i = findIndex(list, id);
+    if (i < 0)
+        return list.slice();
+    return [...list.slice(0, i), mw, ...list.slice(i)];
+};
+/** Insert a step after the step with given id. */
+const insertAfter = (list, id, mw) => {
+    const i = findIndex(list, id);
+    if (i < 0)
+        return list.slice();
+    return [...list.slice(0, i + 1), mw, ...list.slice(i + 1)];
+};
+/** Replace a step with given id. */
+const replaceStep = (list, id, mw) => {
+    const i = findIndex(list, id);
+    if (i < 0)
+        return list.slice();
+    const out = list.slice();
+    out[i] = mw;
+    return out;
+};
+/** Remove a step with given id. */
+const removeStep = (list, id) => {
+    const i = findIndex(list, id);
+    if (i < 0)
+        return list.slice();
+    return [...list.slice(0, i), ...list.slice(i + 1)];
+};
+
+/**
+ * Path utilities for cross-platform hygiene.
+ *
+ * - toPosixPath: normalize Windows backslashes to POSIX separators.
+ * - dirFromHere: resolve a directory from an import.meta.url, N levels up,
+ *   returning a POSIX-normalized absolute path.
+ */
+/** Normalize a path to POSIX separators. */
+const toPosixPath = (p) => p.replace(/\\/g, '/');
+/**
+ * Resolve a directory path relative to the current module URL and normalize it.
+ *
+ * @param metaUrl - typically import.meta.url
+ * @param levelsUp - how many directory levels to ascend (default: 1)
+ * @returns absolute, POSIX-normalized directory path
+ */
+const dirFromHere = (metaUrl, levelsUp = 1) => {
+    // Build a URL like '../' repeated N times, resolved from metaUrl.
+    const up = Array.from({ length: Math.max(0, levelsUp) })
+        .map(() => '..')
+        .join('/');
+    const url = new URL(`${up}/`, metaUrl);
+    const abs = fileURLToPath(url);
+    return toPosixPath(abs);
+};
+
+export { App, baseEventTypeMapSchema, buildSafeDefaults, defineAppConfig, detectSecurityContext, dirFromHere, findIndex, getId, insertAfter, insertBefore, removeStep, replaceStep, tagStep, toPosixPath, wrapHandler };