@tulipes/core 0.1.0

package/dist/env/spec.d.ts

@@ -0,0 +1,133 @@
+import { z } from "zod";
+/**
+ * Schema for one entry in a module's `meta.variables.json`.
+ *
+ * The file is deliberately plain JSON (not TS): tooling — `.env.example`
+ * generation, docs, the postman generator — must be able to read a module's
+ * env contract without executing its code.
+ */
+export declare const variableTypes: readonly ["string", "number", "boolean", "enum", "url", 
+/** Same as string, but redacted in logs, reports and snapshots. */
+"secret"];
+export type VariableType = (typeof variableTypes)[number];
+/** Values a variable can resolve to after coercion. */
+export type VariableValue = string | number | boolean;
+export declare const variableSpecSchema: z.ZodEffects<z.ZodObject<{
+    name: z.ZodString;
+    type: z.ZodEnum<["string", "number", "boolean", "enum", "url", "secret"]>;
+    description: z.ZodString;
+    /**
+     * Free-form label tying related variables together (e.g. every Mongo
+     * credential under "database") — drives section grouping in generated
+     * .env.example / docs. Purely organizational, hence optional.
+     */
+    group: z.ZodOptional<z.ZodString>;
+    enum: z.ZodOptional<z.ZodArray<z.ZodString, "atleastone">>;
+    required: z.ZodOptional<z.ZodBoolean>;
+    default: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    type: "boolean" | "enum" | "number" | "secret" | "string" | "url";
+    description: string;
+    group?: string | undefined;
+    enum?: [string, ...string[]] | undefined;
+    required?: boolean | undefined;
+    default?: string | number | boolean | undefined;
+}, {
+    name: string;
+    type: "boolean" | "enum" | "number" | "secret" | "string" | "url";
+    description: string;
+    group?: string | undefined;
+    enum?: [string, ...string[]] | undefined;
+    required?: boolean | undefined;
+    default?: string | number | boolean | undefined;
+}>, {
+    name: string;
+    type: "boolean" | "enum" | "number" | "secret" | "string" | "url";
+    description: string;
+    group?: string | undefined;
+    enum?: [string, ...string[]] | undefined;
+    required?: boolean | undefined;
+    default?: string | number | boolean | undefined;
+}, {
+    name: string;
+    type: "boolean" | "enum" | "number" | "secret" | "string" | "url";
+    description: string;
+    group?: string | undefined;
+    enum?: [string, ...string[]] | undefined;
+    required?: boolean | undefined;
+    default?: string | number | boolean | undefined;
+}>;
+export type VariableSpec = z.infer<typeof variableSpecSchema>;
+export declare const metaFileSchema: z.ZodObject<{
+    $schema: z.ZodOptional<z.ZodString>;
+    variables: z.ZodArray<z.ZodEffects<z.ZodObject<{
+        name: z.ZodString;
+        type: z.ZodEnum<["string", "number", "boolean", "enum", "url", "secret"]>;
+        description: z.ZodString;
+        /**
+         * Free-form label tying related variables together (e.g. every Mongo
+         * credential under "database") — drives section grouping in generated
+         * .env.example / docs. Purely organizational, hence optional.
+         */
+        group: z.ZodOptional<z.ZodString>;
+        enum: z.ZodOptional<z.ZodArray<z.ZodString, "atleastone">>;
+        required: z.ZodOptional<z.ZodBoolean>;
+        default: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
+    }, "strip", z.ZodTypeAny, {
+        name: string;
+        type: "boolean" | "enum" | "number" | "secret" | "string" | "url";
+        description: string;
+        group?: string | undefined;
+        enum?: [string, ...string[]] | undefined;
+        required?: boolean | undefined;
+        default?: string | number | boolean | undefined;
+    }, {
+        name: string;
+        type: "boolean" | "enum" | "number" | "secret" | "string" | "url";
+        description: string;
+        group?: string | undefined;
+        enum?: [string, ...string[]] | undefined;
+        required?: boolean | undefined;
+        default?: string | number | boolean | undefined;
+    }>, {
+        name: string;
+        type: "boolean" | "enum" | "number" | "secret" | "string" | "url";
+        description: string;
+        group?: string | undefined;
+        enum?: [string, ...string[]] | undefined;
+        required?: boolean | undefined;
+        default?: string | number | boolean | undefined;
+    }, {
+        name: string;
+        type: "boolean" | "enum" | "number" | "secret" | "string" | "url";
+        description: string;
+        group?: string | undefined;
+        enum?: [string, ...string[]] | undefined;
+        required?: boolean | undefined;
+        default?: string | number | boolean | undefined;
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    $schema?: string | undefined;
+    variables: {
+        name: string;
+        type: "boolean" | "enum" | "number" | "secret" | "string" | "url";
+        description: string;
+        group?: string | undefined;
+        enum?: [string, ...string[]] | undefined;
+        required?: boolean | undefined;
+        default?: string | number | boolean | undefined;
+    }[];
+}, {
+    $schema?: string | undefined;
+    variables: {
+        name: string;
+        type: "boolean" | "enum" | "number" | "secret" | "string" | "url";
+        description: string;
+        group?: string | undefined;
+        enum?: [string, ...string[]] | undefined;
+        required?: boolean | undefined;
+        default?: string | number | boolean | undefined;
+    }[];
+}>;
+export type MetaFile = z.infer<typeof metaFileSchema>;

package/dist/env/spec.js

@@ -0,0 +1,63 @@
+import { z } from "zod";
+/**
+ * Schema for one entry in a module's `meta.variables.json`.
+ *
+ * The file is deliberately plain JSON (not TS): tooling — `.env.example`
+ * generation, docs, the postman generator — must be able to read a module's
+ * env contract without executing its code.
+ */
+export const variableTypes = [
+    "string",
+    "number",
+    "boolean",
+    "enum",
+    "url",
+    /** Same as string, but redacted in logs, reports and snapshots. */
+    "secret",
+];
+const VARIABLE_NAME = /^[A-Z][A-Z0-9_]*$/;
+export const variableSpecSchema = z
+    .object({
+    name: z
+        .string()
+        .regex(VARIABLE_NAME, "must be UPPER_SNAKE_CASE (e.g. USERS_MAX_SESSIONS)"),
+    type: z.enum(variableTypes),
+    description: z.string().min(1),
+    /**
+     * Free-form label tying related variables together (e.g. every Mongo
+     * credential under "database") — drives section grouping in generated
+     * .env.example / docs. Purely organizational, hence optional.
+     */
+    group: z.string().min(1).optional(),
+    enum: z.array(z.string()).nonempty().optional(),
+    required: z.boolean().optional(),
+    default: z.union([z.string(), z.number(), z.boolean()]).optional(),
+})
+    .superRefine((spec, ctx) => {
+    // These pairings can't be expressed structurally, so they live here:
+    if (spec.type === "enum" && !spec.enum) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: `"${spec.name}": type "enum" requires an "enum" value list`,
+        });
+    }
+    if (spec.type !== "enum" && spec.enum) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: `"${spec.name}": "enum" list is only valid with type "enum"`,
+        });
+    }
+    // required means "the deployment must supply it" — a default would
+    // silently defeat that, so the combination is rejected outright.
+    if (spec.required && spec.default !== undefined) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: `"${spec.name}": "required" and "default" are mutually exclusive`,
+        });
+    }
+});
+export const metaFileSchema = z.object({
+    $schema: z.string().optional(),
+    variables: z.array(variableSpecSchema),
+});
+//# sourceMappingURL=spec.js.map

package/dist/env/spec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spec.js","sourceRoot":"","sources":["../../src/env/spec.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;GAMG;AAEH,MAAM,CAAC,MAAM,aAAa,GAAG;IAC3B,QAAQ;IACR,QAAQ;IACR,SAAS;IACT,MAAM;IACN,KAAK;IACL,mEAAmE;IACnE,QAAQ;CACA,CAAC;AAOX,MAAM,aAAa,GAAG,mBAAmB,CAAC;AAE1C,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC;KAChC,MAAM,CAAC;IACN,IAAI,EAAE,CAAC;SACJ,MAAM,EAAE;SACR,KAAK,CAAC,aAAa,EAAE,oDAAoD,CAAC;IAC7E,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC;IAC3B,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC9B;;;;OAIG;IACH,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;IACnC,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE;IAC/C,QAAQ,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;IAChC,OAAO,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,QAAQ,EAAE;CACnE,CAAC;KACD,WAAW,CAAC,CAAC,IAAI,EAAE,GAAG,EAAE,EAAE;IACzB,qEAAqE;IACrE,IAAI,IAAI,CAAC,IAAI,KAAK,MAAM,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;QACvC,GAAG,CAAC,QAAQ,CAAC;YACX,IAAI,EAAE,CAAC,CAAC,YAAY,CAAC,MAAM;YAC3B,OAAO,EAAE,IAAI,IAAI,CAAC,IAAI,8CAA8C;SACrE,CAAC,CAAC;IACL,CAAC;IACD,IAAI,IAAI,CAAC,IAAI,KAAK,MAAM,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;QACtC,GAAG,CAAC,QAAQ,CAAC;YACX,IAAI,EAAE,CAAC,CAAC,YAAY,CAAC,MAAM;YAC3B,OAAO,EAAE,IAAI,IAAI,CAAC,IAAI,+CAA+C;SACtE,CAAC,CAAC;IACL,CAAC;IACD,mEAAmE;IACnE,iEAAiE;IACjE,IAAI,IAAI,CAAC,QAAQ,IAAI,IAAI,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;QAChD,GAAG,CAAC,QAAQ,CAAC;YACX,IAAI,EAAE,CAAC,CAAC,YAAY,CAAC,MAAM;YAC3B,OAAO,EAAE,IAAI,IAAI,CAAC,IAAI,oDAAoD;SAC3E,CAAC,CAAC;IACL,CAAC;AACH,CAAC,CAAC,CAAC;AAIL,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,CAAC,MAAM,CAAC;IACrC,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC9B,SAAS,EAAE,CAAC,CAAC,KAAK,CAAC,kBAAkB,CAAC;CACvC,CAAC,CAAC"}

package/dist/env/variable-store.d.ts

@@ -0,0 +1,26 @@
+import type { VariableSpec, VariableValue } from "./spec.js";
+/**
+ * The resolved, validated variable store the rest of the framework reads from.
+ *
+ * Fail-closed on the read side too: asking for a variable no module declared
+ * throws immediately instead of returning undefined — an undeclared read is
+ * always a bug (either a typo, or a missing meta.variables.json entry), and
+ * surfacing it at the call site beats debugging an undefined downstream.
+ */
+export declare class VariableStore {
+    #private;
+    /** @internal Populated by the Environment engine during boot. */
+    declare_(spec: VariableSpec, owner: string, value: VariableValue): void;
+    has(name: string): boolean;
+    get<T extends VariableValue = VariableValue>(name: string): T;
+    /** Runtime override — primarily for tests. The variable must be declared. */
+    set(name: string, value: VariableValue): void;
+    ownerOf(name: string): string | undefined;
+    /**
+     * Flat view for logging / debugging. Secrets are redacted by default and
+     * opting out is deliberately loud in the caller's code.
+     */
+    snapshot(options?: {
+        revealSecrets?: boolean;
+    }): Record<string, VariableValue>;
+}

package/dist/env/variable-store.js

@@ -0,0 +1,49 @@
+/**
+ * The resolved, validated variable store the rest of the framework reads from.
+ *
+ * Fail-closed on the read side too: asking for a variable no module declared
+ * throws immediately instead of returning undefined — an undeclared read is
+ * always a bug (either a typo, or a missing meta.variables.json entry), and
+ * surfacing it at the call site beats debugging an undefined downstream.
+ */
+export class VariableStore {
+    #variables = new Map();
+    /** @internal Populated by the Environment engine during boot. */
+    declare_(spec, owner, value) {
+        this.#variables.set(spec.name, { spec, owner, value });
+    }
+    has(name) {
+        return this.#variables.has(name);
+    }
+    get(name) {
+        const stored = this.#variables.get(name);
+        if (!stored) {
+            throw new Error(`Environment variable "${name}" was never declared by any module's meta.variables.json`);
+        }
+        return stored.value;
+    }
+    /** Runtime override — primarily for tests. The variable must be declared. */
+    set(name, value) {
+        const stored = this.#variables.get(name);
+        if (!stored) {
+            throw new Error(`Cannot set undeclared environment variable "${name}"`);
+        }
+        stored.value = value;
+    }
+    ownerOf(name) {
+        return this.#variables.get(name)?.owner;
+    }
+    /**
+     * Flat view for logging / debugging. Secrets are redacted by default and
+     * opting out is deliberately loud in the caller's code.
+     */
+    snapshot(options = {}) {
+        const view = {};
+        for (const [name, { spec, value }] of this.#variables) {
+            view[name] =
+                spec.type === "secret" && !options.revealSecrets ? "•••" : value;
+        }
+        return view;
+    }
+}
+//# sourceMappingURL=variable-store.js.map

package/dist/env/variable-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"variable-store.js","sourceRoot":"","sources":["../../src/env/variable-store.ts"],"names":[],"mappings":"AASA;;;;;;;GAOG;AACH,MAAM,OAAO,aAAa;IACf,UAAU,GAAG,IAAI,GAAG,EAA0B,CAAC;IAExD,iEAAiE;IACjE,QAAQ,CAAC,IAAkB,EAAE,KAAa,EAAE,KAAoB;QAC9D,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;IACzD,CAAC;IAED,GAAG,CAAC,IAAY;QACd,OAAO,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACnC,CAAC;IAED,GAAG,CAA0C,IAAY;QACvD,MAAM,MAAM,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACzC,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,MAAM,IAAI,KAAK,CACb,yBAAyB,IAAI,0DAA0D,CACxF,CAAC;QACJ,CAAC;QACD,OAAO,MAAM,CAAC,KAAU,CAAC;IAC3B,CAAC;IAED,6EAA6E;IAC7E,GAAG,CAAC,IAAY,EAAE,KAAoB;QACpC,MAAM,MAAM,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACzC,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,MAAM,IAAI,KAAK,CAAC,+CAA+C,IAAI,GAAG,CAAC,CAAC;QAC1E,CAAC;QACD,MAAM,CAAC,KAAK,GAAG,KAAK,CAAC;IACvB,CAAC;IAED,OAAO,CAAC,IAAY;QAClB,OAAO,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,KAAK,CAAC;IAC1C,CAAC;IAED;;;OAGG;IACH,QAAQ,CAAC,OAAO,GAAgC,EAAE;QAChD,MAAM,IAAI,GAAkC,EAAE,CAAC;QAC/C,KAAK,MAAM,CAAC,IAAI,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;YACtD,IAAI,CAAC,IAAI,CAAC;gBACR,IAAI,CAAC,IAAI,KAAK,QAAQ,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC;QACrE,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;CACF"}

package/dist/errors/boot-error.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Tulipes fails closed at boot: a phase never crashes on the first problem it
+ * meets. It collects everything wrong, then throws once with the full list —
+ * so a developer with ten missing env variables fixes ten, not one per restart.
+ */
+export type BootScope = "env" | "modules" | "config" | "acl" | "boot";
+export interface BootIssue {
+    scope: BootScope;
+    /** Module short-name, when the issue is attributable to a single module. */
+    module?: string;
+    message: string;
+}
+export declare class TulipesBootError extends Error {
+    #private;
+    readonly phase: string;
+    readonly issues: readonly BootIssue[];
+    constructor(phase: string, issues: readonly BootIssue[]);
+}
+/**
+ * Shared collector passed through a boot phase. Engines `add()` freely;
+ * the phase driver calls `throwIfAny()` at its checkpoint.
+ */
+export declare class BootReport {
+    #private;
+    add(issue: BootIssue): void;
+    get issues(): readonly BootIssue[];
+    throwIfAny(phase: string): void;
+}

package/dist/errors/boot-error.js

@@ -0,0 +1,44 @@
+/**
+ * Tulipes fails closed at boot: a phase never crashes on the first problem it
+ * meets. It collects everything wrong, then throws once with the full list —
+ * so a developer with ten missing env variables fixes ten, not one per restart.
+ */
+export class TulipesBootError extends Error {
+    phase;
+    issues;
+    constructor(phase, issues) {
+        super(TulipesBootError.#format(phase, issues));
+        this.name = "TulipesBootError";
+        this.phase = phase;
+        this.issues = issues;
+    }
+    static #format(phase, issues) {
+        const lines = issues.map((issue) => {
+            const origin = issue.module ? `[${issue.module}] ` : "";
+            return `  ✖ ${origin}${issue.message}`;
+        });
+        return [
+            `Boot aborted during "${phase}" — ${issues.length} issue(s):`,
+            ...lines,
+        ].join("\n");
+    }
+}
+/**
+ * Shared collector passed through a boot phase. Engines `add()` freely;
+ * the phase driver calls `throwIfAny()` at its checkpoint.
+ */
+export class BootReport {
+    #issues = [];
+    add(issue) {
+        this.#issues.push(issue);
+    }
+    get issues() {
+        return this.#issues;
+    }
+    throwIfAny(phase) {
+        if (this.#issues.length > 0) {
+            throw new TulipesBootError(phase, this.#issues);
+        }
+    }
+}
+//# sourceMappingURL=boot-error.js.map

package/dist/errors/boot-error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"boot-error.js","sourceRoot":"","sources":["../../src/errors/boot-error.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAWH,MAAM,OAAO,gBAAiB,SAAQ,KAAK;IAChC,KAAK,CAAS;IACd,MAAM,CAAuB;IAEtC,YAAY,KAAa,EAAE,MAA4B;QACrD,KAAK,CAAC,gBAAgB,CAAC,OAAO,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,CAAC;QAC/C,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAC;QAC/B,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;IAED,MAAM,CAAC,OAAO,CAAC,KAAa,EAAE,MAA4B;QACxD,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE;YACjC,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;YACxD,OAAO,OAAO,MAAM,GAAG,KAAK,CAAC,OAAO,EAAE,CAAC;QACzC,CAAC,CAAC,CAAC;QACH,OAAO;YACL,wBAAwB,KAAK,OAAO,MAAM,CAAC,MAAM,YAAY;YAC7D,GAAG,KAAK;SACT,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACf,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,OAAO,UAAU;IACZ,OAAO,GAAgB,EAAE,CAAC;IAEnC,GAAG,CAAC,KAAgB;QAClB,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAC3B,CAAC;IAED,IAAI,MAAM;QACR,OAAO,IAAI,CAAC,OAAO,CAAC;IACtB,CAAC;IAED,UAAU,CAAC,KAAa;QACtB,IAAI,IAAI,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC5B,MAAM,IAAI,gBAAgB,CAAC,KAAK,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;QAClD,CAAC;IACH,CAAC;CACF"}

package/dist/errors/index.d.ts

@@ -0,0 +1 @@
+export { BootReport, TulipesBootError, type BootIssue, type BootScope, } from "./boot-error.js";

package/dist/errors/index.js

@@ -0,0 +1,2 @@
+export { BootReport, TulipesBootError, } from "./boot-error.js";
+//# sourceMappingURL=index.js.map

package/dist/errors/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/errors/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,UAAU,EACV,gBAAgB,GAGjB,MAAM,iBAAiB,CAAC"}

package/dist/http/error-handler.d.ts

@@ -0,0 +1,23 @@
+import type { ErrorRequestHandler, RequestHandler } from "express";
+import type { AppEnv } from "../env/environment.js";
+/**
+ * The error a route throws on purpose. Anything else reaching the error
+ * handler is a bug and gets the anonymous-500 treatment.
+ *
+ * Express 5 forwards rejected async handlers to the error middleware
+ * automatically, so `throw new HttpError(404, "no such user")` inside an
+ * async route is the entire error-handling story a module needs.
+ */
+export declare class HttpError extends Error {
+    readonly status: number;
+    readonly details?: unknown;
+    constructor(status: number, message: string, details?: unknown);
+}
+/** Terminal 404 — anything no router claimed. */
+export declare function notFoundHandler(): RequestHandler;
+/**
+ * The single, final error middleware. Fail-closed on information leaks:
+ * unexpected errors expose no message, no stack, nothing — except in
+ * development, where hiding them only slows the developer down.
+ */
+export declare function errorHandler(appEnv: AppEnv): ErrorRequestHandler;

package/dist/http/error-handler.js

@@ -0,0 +1,48 @@
+/**
+ * The error a route throws on purpose. Anything else reaching the error
+ * handler is a bug and gets the anonymous-500 treatment.
+ *
+ * Express 5 forwards rejected async handlers to the error middleware
+ * automatically, so `throw new HttpError(404, "no such user")` inside an
+ * async route is the entire error-handling story a module needs.
+ */
+export class HttpError extends Error {
+    status;
+    details;
+    constructor(status, message, details) {
+        super(message);
+        this.name = "HttpError";
+        this.status = status;
+        this.details = details;
+    }
+}
+/** Terminal 404 — anything no router claimed. */
+export function notFoundHandler() {
+    return (req, _res, next) => {
+        next(new HttpError(404, `no route for ${req.method} ${req.path}`));
+    };
+}
+/**
+ * The single, final error middleware. Fail-closed on information leaks:
+ * unexpected errors expose no message, no stack, nothing — except in
+ * development, where hiding them only slows the developer down.
+ */
+export function errorHandler(appEnv) {
+    const revealInternals = appEnv === "development" || appEnv === "test";
+    return (error, _req, res, _next) => {
+        if (error instanceof HttpError) {
+            res.status(error.status).json({
+                error: error.message,
+                ...(error.details !== undefined && { details: error.details }),
+            });
+            return;
+        }
+        console.error("[http] unhandled error:", error);
+        res.status(500).json({
+            error: revealInternals
+                ? `internal: ${error?.message ?? String(error)}`
+                : "internal server error",
+        });
+    };
+}
+//# sourceMappingURL=error-handler.js.map

package/dist/http/error-handler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-handler.js","sourceRoot":"","sources":["../../src/http/error-handler.ts"],"names":[],"mappings":"AAIA;;;;;;;GAOG;AACH,MAAM,OAAO,SAAU,SAAQ,KAAK;IACzB,MAAM,CAAS;IACf,OAAO,CAAW;IAE3B,YAAY,MAAc,EAAE,OAAe,EAAE,OAAiB;QAC5D,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,WAAW,CAAC;QACxB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACzB,CAAC;CACF;AAED,iDAAiD;AACjD,MAAM,UAAU,eAAe;IAC7B,OAAO,CAAC,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE;QACzB,IAAI,CAAC,IAAI,SAAS,CAAC,GAAG,EAAE,gBAAgB,GAAG,CAAC,MAAM,IAAI,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;IACrE,CAAC,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAAC,MAAc;IACzC,MAAM,eAAe,GAAG,MAAM,KAAK,aAAa,IAAI,MAAM,KAAK,MAAM,CAAC;IAEtE,OAAO,CAAC,KAAc,EAAE,IAAI,EAAE,GAAG,EAAE,KAAK,EAAE,EAAE;QAC1C,IAAI,KAAK,YAAY,SAAS,EAAE,CAAC;YAC/B,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC;gBAC5B,KAAK,EAAE,KAAK,CAAC,OAAO;gBACpB,GAAG,CAAC,KAAK,CAAC,OAAO,KAAK,SAAS,IAAI,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,CAAC;aAC/D,CAAC,CAAC;YACH,OAAO;QACT,CAAC;QAED,OAAO,CAAC,KAAK,CAAC,yBAAyB,EAAE,KAAK,CAAC,CAAC;QAChD,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC;YACnB,KAAK,EAAE,eAAe;gBACpB,CAAC,CAAC,aAAc,KAAe,EAAE,OAAO,IAAI,MAAM,CAAC,KAAK,CAAC,EAAE;gBAC3D,CAAC,CAAC,uBAAuB;SAC5B,CAAC,CAAC;IACL,CAAC,CAAC;AACJ,CAAC"}

package/dist/http/index.d.ts

@@ -0,0 +1 @@
+export { HttpError, errorHandler, notFoundHandler } from "./error-handler.js";

package/dist/http/index.js

@@ -0,0 +1,2 @@
+export { HttpError, errorHandler, notFoundHandler } from "./error-handler.js";
+//# sourceMappingURL=index.js.map

package/dist/http/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/http/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+export * from "./acl/index.js";
+export * from "./boot/index.js";
+export * from "./config/index.js";
+export * from "./db/index.js";
+export * from "./env/index.js";
+export * from "./http/index.js";
+export * from "./modules/index.js";
+export * from "./queues/index.js";
+export * from "./sockets/index.js";
+export * from "./errors/index.js";

package/dist/index.js

@@ -0,0 +1,11 @@
+export * from "./acl/index.js";
+export * from "./boot/index.js";
+export * from "./config/index.js";
+export * from "./db/index.js";
+export * from "./env/index.js";
+export * from "./http/index.js";
+export * from "./modules/index.js";
+export * from "./queues/index.js";
+export * from "./sockets/index.js";
+export * from "./errors/index.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC;AAC/B,cAAc,iBAAiB,CAAC;AAChC,cAAc,mBAAmB,CAAC;AAClC,cAAc,eAAe,CAAC;AAC9B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,iBAAiB,CAAC;AAChC,cAAc,oBAAoB,CAAC;AACnC,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,mBAAmB,CAAC"}

package/dist/modules/discovery.d.ts

@@ -0,0 +1,10 @@
+import { BootReport } from "../errors/boot-error.js";
+import { type ModuleManifest } from "./manifest.js";
+/**
+ * Read each module's package.json (under `modules/<name>`) into a manifest.
+ * Modules are yarn
+ * workspace packages, so a folder without a package.json is a broken module,
+ * not an ignorable one. As everywhere at boot: problems are collected into
+ * the report, never thrown one-by-one.
+ */
+export declare function discoverModules(modulesDir: string, report: BootReport): ModuleManifest[];

package/dist/modules/discovery.js

@@ -0,0 +1,91 @@
+import { readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { BootReport } from "../errors/boot-error.js";
+import { tulipesManifestSchema } from "./manifest.js";
+/**
+ * Read each module's package.json (under `modules/<name>`) into a manifest.
+ * Modules are yarn
+ * workspace packages, so a folder without a package.json is a broken module,
+ * not an ignorable one. As everywhere at boot: problems are collected into
+ * the report, never thrown one-by-one.
+ */
+export function discoverModules(modulesDir, report) {
+    let entries;
+    try {
+        entries = readdirSync(modulesDir, { withFileTypes: true });
+    }
+    catch {
+        report.add({
+            scope: "modules",
+            message: `modules directory not found: ${modulesDir}`,
+        });
+        return [];
+    }
+    const manifests = [];
+    const seen = new Map(); // short name → package name
+    for (const entry of entries) {
+        if (!entry.isDirectory() || entry.name.startsWith("."))
+            continue;
+        const dir = join(modulesDir, entry.name);
+        const manifest = readManifest(dir, entry.name, report);
+        if (!manifest)
+            continue;
+        // Short names must be unique: they are the dependsOn address space.
+        // Two scopes owning the same segment (@a/users, @b/users) would make
+        // "dependsOn: [users]" ambiguous.
+        const clash = seen.get(manifest.name);
+        if (clash) {
+            report.add({
+                scope: "modules",
+                module: manifest.name,
+                message: `short name "${manifest.name}" is claimed by both "${clash}" and "${manifest.packageName}"`,
+            });
+            continue;
+        }
+        seen.set(manifest.name, manifest.packageName);
+        manifests.push(manifest);
+    }
+    return manifests;
+}
+function readManifest(dir, folder, report) {
+    let json;
+    try {
+        json = JSON.parse(readFileSync(join(dir, "package.json"), "utf8"));
+    }
+    catch (error) {
+        report.add({
+            scope: "modules",
+            module: folder,
+            message: `package.json missing or invalid: ${error.message}`,
+        });
+        return undefined;
+    }
+    if (typeof json.name !== "string" || json.name.length === 0) {
+        report.add({
+            scope: "modules",
+            module: folder,
+            message: `package.json has no "name" — modules must be workspace packages`,
+        });
+        return undefined;
+    }
+    // Absent "tulipes" key is a valid module with default ordering.
+    const parsed = tulipesManifestSchema.safeParse(json.tulipes ?? {});
+    if (!parsed.success) {
+        for (const issue of parsed.error.issues) {
+            report.add({
+                scope: "modules",
+                module: folder,
+                message: `package.json "tulipes" key: ${issue.path.join(".") || "(root)"} — ${issue.message}`,
+            });
+        }
+        return undefined;
+    }
+    const shortName = json.name.split("/").at(-1);
+    return {
+        name: shortName,
+        packageName: json.name,
+        dir,
+        ...parsed.data,
+    };
+}
+//# sourceMappingURL=discovery.js.map

package/dist/modules/discovery.js.map

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

package/dist/modules/explorer.d.ts

@@ -0,0 +1,38 @@
+import type { ModuleManifest } from "./manifest.js";
+/**
+ * Boot phase 5: given the sorted module list, resolve every conventional file
+ * the loaders will consume — paths only, nothing is imported yet. Importing
+ * happens later, phase by phase, so a broken routes file can't take down the
+ * environment report, and models load before routes exactly as the pipeline
+ * dictates.
+ *
+ * Missing directories and files are simply features a module doesn't use —
+ * never an error. The explorer has no failure modes by design.
+ */
+export type SourceExtension = ".ts" | ".js";
+/**
+ * In dev the app runs straight from TypeScript (via tsx) so conventions
+ * resolve to .ts files; a compiled deployment runs .js from dist. Core infers
+ * which world it's in from its own file — this very file is only ever .js
+ * after a build. The URL alone isn't trustworthy: tsx's tsImport presents
+ * modules under a .js URL while only the .ts source exists on disk, so a
+ * .js verdict is confirmed against the filesystem.
+ */
+export declare function detectSourceExtension(): SourceExtension;
+export interface ModuleFiles {
+    module: ModuleManifest;
+    /** `module.config.<ext>` — config factory + lifecycle hooks. */
+    configFile?: string;
+    /** `module.acl.<ext>` — permission grants for this module's resources. */
+    aclFile?: string;
+    routeFiles: readonly string[];
+    modelFiles: readonly string[];
+    bootstrapFiles: readonly string[];
+    queueFiles: readonly string[];
+    socketFiles: readonly string[];
+}
+export interface ExploreOptions {
+    /** Override the runtime detection — used by tooling and tests. */
+    sourceExtension?: SourceExtension;
+}
+export declare function exploreModules(modules: readonly ModuleManifest[], options?: ExploreOptions): ModuleFiles[];