@tulipes/core 0.1.0

package/dist/db/database.d.ts

@@ -0,0 +1,25 @@
+import { Schema, type Connection } from "mongoose";
+import { BootReport } from "../errors/boot-error.js";
+import type { Ctx } from "../boot/contracts.js";
+import type { ModuleFiles } from "../modules/explorer.js";
+/**
+ * Model files are pure definitions — no factory, no ctx. The loader turns
+ * them into live models on the shared connection.
+ */
+export interface ModelDef {
+    name: string;
+    schema: Schema;
+    /** Override mongoose's automatic collection naming when needed. */
+    collection?: string;
+}
+/** Default export of `bootstrap/*.bootstrap.ts` — post-DB, pre-server init. */
+export type BootstrapFn = (ctx: Ctx) => void | Promise<void>;
+/**
+ * Boot phase 8: connect, register every model in load order, then run every
+ * bootstrap task in load order (indexes, seed roles, default records).
+ *
+ * A DB-less app is legitimate — no models and no MONGO_URI simply skips the
+ * phase. Declaring models *without* a connection string, though, is a
+ * contradiction the boot must refuse.
+ */
+export declare function initDatabase(explored: readonly ModuleFiles[], ctx: Ctx, report: BootReport): Promise<Connection | undefined>;

package/dist/db/database.js

@@ -0,0 +1,111 @@
+import { createConnection, Schema } from "mongoose";
+import { BootReport } from "../errors/boot-error.js";
+import { importFile } from "../boot/import-file.js";
+import { ModelStore } from "./model-store.js";
+/** Well-known infra variable, declared by the app's sys core module. */
+const MONGO_URI = "MONGO_URI";
+/**
+ * Boot phase 8: connect, register every model in load order, then run every
+ * bootstrap task in load order (indexes, seed roles, default records).
+ *
+ * A DB-less app is legitimate — no models and no MONGO_URI simply skips the
+ * phase. Declaring models *without* a connection string, though, is a
+ * contradiction the boot must refuse.
+ */
+export async function initDatabase(explored, ctx, report) {
+    const hasModels = explored.some((files) => files.modelFiles.length > 0);
+    const uri = ctx.Environment.store.has(MONGO_URI)
+        ? String(ctx.Environment.get(MONGO_URI))
+        : undefined;
+    if (!uri) {
+        if (hasModels) {
+            report.add({
+                scope: "boot",
+                message: `modules declare models but "${MONGO_URI}" is not declared/set — a database is required`,
+            });
+        }
+        return undefined;
+    }
+    let connection;
+    try {
+        // Fail fast: default server selection waits 30s before reporting an
+        // unreachable database — far too long for a boot-time verdict.
+        connection = await createConnection(uri, {
+            serverSelectionTimeoutMS: 5_000,
+        }).asPromise();
+    }
+    catch (error) {
+        report.add({
+            scope: "boot",
+            message: `database connection failed (${MONGO_URI}): ${error.message}`,
+        });
+        return undefined;
+    }
+    const store = new ModelStore();
+    ctx.models = store;
+    await registerModels(explored, connection, store, report);
+    // Bootstrap tasks only make sense against a fully-populated model store,
+    // and only when nothing above them failed.
+    if (report.issues.length === 0) {
+        await runBootstrapTasks(explored, ctx, report);
+    }
+    return connection;
+}
+async function registerModels(explored, connection, store, report) {
+    for (const { module, modelFiles } of explored) {
+        for (const file of modelFiles) {
+            const exported = await importFile(file, "boot", module.name, report);
+            if (!exported)
+                continue;
+            const def = exported.default;
+            if (typeof def?.name !== "string" ||
+                !(def.schema instanceof Schema)) {
+                report.add({
+                    scope: "boot",
+                    module: module.name,
+                    message: `${file} must default-export { name, schema } (a ModelDef)`,
+                });
+                continue;
+            }
+            const owner = store.ownerOf(def.name);
+            if (owner) {
+                report.add({
+                    scope: "boot",
+                    module: module.name,
+                    message: `model "${def.name}" is already registered by module "${owner}"`,
+                });
+                continue;
+            }
+            const model = connection.model(def.name, def.schema, def.collection);
+            store.register_(def.name, model, module.name);
+        }
+    }
+}
+async function runBootstrapTasks(explored, ctx, report) {
+    for (const { module, bootstrapFiles } of explored) {
+        for (const file of bootstrapFiles) {
+            const exported = await importFile(file, "boot", module.name, report);
+            if (!exported)
+                continue;
+            if (typeof exported.default !== "function") {
+                report.add({
+                    scope: "boot",
+                    module: module.name,
+                    message: `${file} must default-export a bootstrap function (ctx) => void`,
+                });
+                continue;
+            }
+            try {
+                await exported.default(ctx);
+            }
+            catch (error) {
+                report.add({
+                    scope: "boot",
+                    module: module.name,
+                    message: `bootstrap task ${file} threw: ${error.message}`,
+                });
+            }
+        }
+    }
+}
+//# sourceMappingURL=database.js.map

package/dist/db/database.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"database.js","sourceRoot":"","sources":["../../src/db/database.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,EAAmB,MAAM,UAAU,CAAC;AAErE,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AACrD,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAGpD,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAgB9C,wEAAwE;AACxE,MAAM,SAAS,GAAG,WAAW,CAAC;AAE9B;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,QAAgC,EAChC,GAAQ,EACR,MAAkB;IAElB,MAAM,SAAS,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,UAAU,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IACxE,MAAM,GAAG,GAAG,GAAG,CAAC,WAAW,CAAC,KAAK,CAAC,GAAG,CAAC,SAAS,CAAC;QAC9C,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,WAAW,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QACxC,CAAC,CAAC,SAAS,CAAC;IAEd,IAAI,CAAC,GAAG,EAAE,CAAC;QACT,IAAI,SAAS,EAAE,CAAC;YACd,MAAM,CAAC,GAAG,CAAC;gBACT,KAAK,EAAE,MAAM;gBACb,OAAO,EAAE,+BAA+B,SAAS,gDAAgD;aAClG,CAAC,CAAC;QACL,CAAC;QACD,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,IAAI,UAAsB,CAAC;IAC3B,IAAI,CAAC;QACH,oEAAoE;QACpE,+DAA+D;QAC/D,UAAU,GAAG,MAAM,gBAAgB,CAAC,GAAG,EAAE;YACvC,wBAAwB,EAAE,KAAK;SAChC,CAAC,CAAC,SAAS,EAAE,CAAC;IACjB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,CAAC,GAAG,CAAC;YACT,KAAK,EAAE,MAAM;YACb,OAAO,EAAE,+BAA+B,SAAS,MAAO,KAAe,CAAC,OAAO,EAAE;SAClF,CAAC,CAAC;QACH,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,MAAM,KAAK,GAAG,IAAI,UAAU,EAAE,CAAC;IAC/B,GAAG,CAAC,MAAM,GAAG,KAAK,CAAC;IAEnB,MAAM,cAAc,CAAC,QAAQ,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC;IAE1D,yEAAyE;IACzE,2CAA2C;IAC3C,IAAI,MAAM,CAAC,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC/B,MAAM,iBAAiB,CAAC,QAAQ,EAAE,GAAG,EAAE,MAAM,CAAC,CAAC;IACjD,CAAC;IAED,OAAO,UAAU,CAAC;AACpB,CAAC;AAED,KAAK,UAAU,cAAc,CAC3B,QAAgC,EAChC,UAAsB,EACtB,KAAiB,EACjB,MAAkB;IAElB,KAAK,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,IAAI,QAAQ,EAAE,CAAC;QAC9C,KAAK,MAAM,IAAI,IAAI,UAAU,EAAE,CAAC;YAC9B,MAAM,QAAQ,GAAG,MAAM,UAAU,CAC/B,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,IAAI,EAAE,MAAM,CAClC,CAAC;YACF,IAAI,CAAC,QAAQ;gBAAE,SAAS;YAExB,MAAM,GAAG,GAAG,QAAQ,CAAC,OAAwC,CAAC;YAC9D,IACE,OAAO,GAAG,EAAE,IAAI,KAAK,QAAQ;gBAC7B,CAAC,CAAC,GAAG,CAAC,MAAM,YAAY,MAAM,CAAC,EAC/B,CAAC;gBACD,MAAM,CAAC,GAAG,CAAC;oBACT,KAAK,EAAE,MAAM;oBACb,MAAM,EAAE,MAAM,CAAC,IAAI;oBACnB,OAAO,EAAE,GAAG,IAAI,oDAAoD;iBACrE,CAAC,CAAC;gBACH,SAAS;YACX,CAAC;YAED,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YACtC,IAAI,KAAK,EAAE,CAAC;gBACV,MAAM,CAAC,GAAG,CAAC;oBACT,KAAK,EAAE,MAAM;oBACb,MAAM,EAAE,MAAM,CAAC,IAAI;oBACnB,OAAO,EAAE,UAAU,GAAG,CAAC,IAAI,sCAAsC,KAAK,GAAG;iBAC1E,CAAC,CAAC;gBACH,SAAS;YACX,CAAC;YAED,MAAM,KAAK,GAAG,UAAU,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,UAAU,CAAC,CAAC;YACrE,KAAK,CAAC,SAAS,CAAC,GAAG,CAAC,IAAc,EAAE,KAAc,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC;QACnE,CAAC;IACH,CAAC;AACH,CAAC;AAED,KAAK,UAAU,iBAAiB,CAC9B,QAAgC,EAChC,GAAQ,EACR,MAAkB;IAElB,KAAK,MAAM,EAAE,MAAM,EAAE,cAAc,EAAE,IAAI,QAAQ,EAAE,CAAC;QAClD,KAAK,MAAM,IAAI,IAAI,cAAc,EAAE,CAAC;YAClC,MAAM,QAAQ,GAAG,MAAM,UAAU,CAC/B,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,IAAI,EAAE,MAAM,CAClC,CAAC;YACF,IAAI,CAAC,QAAQ;gBAAE,SAAS;YAExB,IAAI,OAAO,QAAQ,CAAC,OAAO,KAAK,UAAU,EAAE,CAAC;gBAC3C,MAAM,CAAC,GAAG,CAAC;oBACT,KAAK,EAAE,MAAM;oBACb,MAAM,EAAE,MAAM,CAAC,IAAI;oBACnB,OAAO,EAAE,GAAG,IAAI,yDAAyD;iBAC1E,CAAC,CAAC;gBACH,SAAS;YACX,CAAC;YAED,IAAI,CAAC;gBACH,MAAO,QAAQ,CAAC,OAAuB,CAAC,GAAG,CAAC,CAAC;YAC/C,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,MAAM,CAAC,GAAG,CAAC;oBACT,KAAK,EAAE,MAAM;oBACb,MAAM,EAAE,MAAM,CAAC,IAAI;oBACnB,OAAO,EAAE,kBAAkB,IAAI,WAAY,KAAe,CAAC,OAAO,EAAE;iBACrE,CAAC,CAAC;YACL,CAAC;QACH,CAAC;IACH,CAAC;AACH,CAAC"}

package/dist/db/index.d.ts

@@ -0,0 +1,2 @@
+export { initDatabase, type BootstrapFn, type ModelDef } from "./database.js";
+export { ModelStore } from "./model-store.js";

package/dist/db/index.js

@@ -0,0 +1,3 @@
+export { initDatabase } from "./database.js";
+export { ModelStore } from "./model-store.js";
+//# sourceMappingURL=index.js.map

package/dist/db/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/db/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAmC,MAAM,eAAe,CAAC;AAC9E,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/db/model-store.d.ts

@@ -0,0 +1,22 @@
+import type { Model } from "mongoose";
+/**
+ * Global model registry, populated from every module's `models/*.model.ts`
+ * during phase 8.
+ *
+ * Same fail-closed read contract as the variable store: asking for a model
+ * nobody registered throws at the call site — a typo'd model name must never
+ * travel as an undefined into query code.
+ */
+export declare class ModelStore {
+    #private;
+    /** @internal Database loader only. */
+    register_(name: string, model: Model<never>, owner: string): void;
+    has(name: string): boolean;
+    ownerOf(name: string): string | undefined;
+    names(): string[];
+    /**
+     * The generic is a caller-side assertion — the store can't verify it.
+     * Typed accessors per model come with the `tulipes sync` codegen.
+     */
+    get<T = unknown>(name: string): Model<T>;
+}

package/dist/db/model-store.js

@@ -0,0 +1,37 @@
+/**
+ * Global model registry, populated from every module's `models/*.model.ts`
+ * during phase 8.
+ *
+ * Same fail-closed read contract as the variable store: asking for a model
+ * nobody registered throws at the call site — a typo'd model name must never
+ * travel as an undefined into query code.
+ */
+export class ModelStore {
+    /** name → { model, owning module } */
+    #models = new Map();
+    /** @internal Database loader only. */
+    register_(name, model, owner) {
+        this.#models.set(name, { model, owner });
+    }
+    has(name) {
+        return this.#models.has(name);
+    }
+    ownerOf(name) {
+        return this.#models.get(name)?.owner;
+    }
+    names() {
+        return [...this.#models.keys()];
+    }
+    /**
+     * The generic is a caller-side assertion — the store can't verify it.
+     * Typed accessors per model come with the `tulipes sync` codegen.
+     */
+    get(name) {
+        const stored = this.#models.get(name);
+        if (!stored) {
+            throw new Error(`Model "${name}" was never registered by any module (known: ${this.names().join(", ") || "none"})`);
+        }
+        return stored.model;
+    }
+}
+//# sourceMappingURL=model-store.js.map

package/dist/db/model-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"model-store.js","sourceRoot":"","sources":["../../src/db/model-store.ts"],"names":[],"mappings":"AAEA;;;;;;;GAOG;AACH,MAAM,OAAO,UAAU;IACrB,sCAAsC;IAC7B,OAAO,GAAG,IAAI,GAAG,EAAkD,CAAC;IAE7E,sCAAsC;IACtC,SAAS,CAAC,IAAY,EAAE,KAAmB,EAAE,KAAa;QACxD,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;IAC3C,CAAC;IAED,GAAG,CAAC,IAAY;QACd,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAChC,CAAC;IAED,OAAO,CAAC,IAAY;QAClB,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,KAAK,CAAC;IACvC,CAAC;IAED,KAAK;QACH,OAAO,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC;IAClC,CAAC;IAED;;;OAGG;IACH,GAAG,CAAc,IAAY;QAC3B,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACtC,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,MAAM,IAAI,KAAK,CACb,UAAU,IAAI,gDAAgD,IAAI,CAAC,KAAK,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,MAAM,GAAG,CACnG,CAAC;QACJ,CAAC;QACD,OAAO,MAAM,CAAC,KAA4B,CAAC;IAC7C,CAAC;CACF"}

package/dist/env/coerce.d.ts

@@ -0,0 +1,17 @@
+import type { VariableSpec, VariableValue } from "./spec.js";
+/**
+ * Turn a raw value (a string from the shell / .env file, or a typed JSON
+ * default) into the type its spec declares — or explain why it can't be.
+ *
+ * Env sources only ever give us strings, while JSON defaults arrive already
+ * typed; both funnel through here so a bad *default* is caught with the same
+ * rigor as a bad deployment value.
+ */
+export type CoerceResult = {
+    ok: true;
+    value: VariableValue;
+} | {
+    ok: false;
+    reason: string;
+};
+export declare function coerceValue(spec: VariableSpec, raw: VariableValue): CoerceResult;

package/dist/env/coerce.js

@@ -0,0 +1,53 @@
+const TRUTHY = new Set(["true", "1", "yes", "on"]);
+const FALSY = new Set(["false", "0", "no", "off"]);
+export function coerceValue(spec, raw) {
+    switch (spec.type) {
+        case "string":
+        case "secret":
+            return typeof raw === "string"
+                ? { ok: true, value: raw }
+                : { ok: false, reason: `expected a string, got ${typeof raw}` };
+        case "number": {
+            if (typeof raw === "number")
+                return { ok: true, value: raw };
+            const parsed = Number(raw);
+            return Number.isFinite(parsed)
+                ? { ok: true, value: parsed }
+                : { ok: false, reason: `"${String(raw)}" is not a number` };
+        }
+        case "boolean": {
+            if (typeof raw === "boolean")
+                return { ok: true, value: raw };
+            const normalized = String(raw).trim().toLowerCase();
+            if (TRUTHY.has(normalized))
+                return { ok: true, value: true };
+            if (FALSY.has(normalized))
+                return { ok: true, value: false };
+            return {
+                ok: false,
+                reason: `"${String(raw)}" is not a boolean (use true/false, 1/0, yes/no, on/off)`,
+            };
+        }
+        case "enum": {
+            const value = String(raw);
+            // spec.enum presence is guaranteed by schema validation upstream.
+            return spec.enum.includes(value)
+                ? { ok: true, value }
+                : {
+                    ok: false,
+                    reason: `"${value}" is not one of: ${spec.enum.join(", ")}`,
+                };
+        }
+        case "url": {
+            const value = String(raw);
+            try {
+                new URL(value);
+                return { ok: true, value };
+            }
+            catch {
+                return { ok: false, reason: `"${value}" is not a valid URL` };
+            }
+        }
+    }
+}
+//# sourceMappingURL=coerce.js.map

package/dist/env/coerce.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"coerce.js","sourceRoot":"","sources":["../../src/env/coerce.ts"],"names":[],"mappings":"AAeA,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,CAAC,MAAM,EAAE,GAAG,EAAE,KAAK,EAAE,IAAI,CAAC,CAAC,CAAC;AACnD,MAAM,KAAK,GAAG,IAAI,GAAG,CAAC,CAAC,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC;AAEnD,MAAM,UAAU,WAAW,CAAC,IAAkB,EAAE,GAAkB;IAChE,QAAQ,IAAI,CAAC,IAAI,EAAE,CAAC;QAClB,KAAK,QAAQ,CAAC;QACd,KAAK,QAAQ;YACX,OAAO,OAAO,GAAG,KAAK,QAAQ;gBAC5B,CAAC,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,EAAE;gBAC1B,CAAC,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,0BAA0B,OAAO,GAAG,EAAE,EAAE,CAAC;QAEpE,KAAK,QAAQ,EAAE,CAAC;YACd,IAAI,OAAO,GAAG,KAAK,QAAQ;gBAAE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC;YAC7D,MAAM,MAAM,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;YAC3B,OAAO,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC;gBAC5B,CAAC,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,EAAE;gBAC7B,CAAC,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,MAAM,CAAC,GAAG,CAAC,mBAAmB,EAAE,CAAC;QAChE,CAAC;QAED,KAAK,SAAS,EAAE,CAAC;YACf,IAAI,OAAO,GAAG,KAAK,SAAS;gBAAE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC;YAC9D,MAAM,UAAU,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;YACpD,IAAI,MAAM,CAAC,GAAG,CAAC,UAAU,CAAC;gBAAE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;YAC7D,IAAI,KAAK,CAAC,GAAG,CAAC,UAAU,CAAC;gBAAE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;YAC7D,OAAO;gBACL,EAAE,EAAE,KAAK;gBACT,MAAM,EAAE,IAAI,MAAM,CAAC,GAAG,CAAC,0DAA0D;aAClF,CAAC;QACJ,CAAC;QAED,KAAK,MAAM,EAAE,CAAC;YACZ,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;YAC1B,kEAAkE;YAClE,OAAO,IAAI,CAAC,IAAK,CAAC,QAAQ,CAAC,KAAK,CAAC;gBAC/B,CAAC,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE;gBACrB,CAAC,CAAC;oBACE,EAAE,EAAE,KAAK;oBACT,MAAM,EAAE,IAAI,KAAK,oBAAoB,IAAI,CAAC,IAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE;iBAC7D,CAAC;QACR,CAAC;QAED,KAAK,KAAK,EAAE,CAAC;YACX,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;YAC1B,IAAI,CAAC;gBACH,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC;gBACf,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;YAC7B,CAAC;YAAC,MAAM,CAAC;gBACP,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,KAAK,sBAAsB,EAAE,CAAC;YAChE,CAAC;QACH,CAAC;IACH,CAAC;AACH,CAAC"}

package/dist/env/environment.d.ts

@@ -0,0 +1,42 @@
+import { VariableStore } from "./variable-store.js";
+import type { VariableValue } from "./spec.js";
+import type { KnownVariables } from "./index.js";
+/** Falls back to the broad VariableValue until codegen narrows the key. */
+type Resolved<K extends string> = K extends keyof KnownVariables ? KnownVariables[K] : VariableValue;
+/**
+ * APP_ENV drives which .env file loads. It is deliberately NOT NODE_ENV:
+ * bundlers and libraries overload NODE_ENV as an optimization flag, so Tulipes
+ * keeps its own axis and mirrors a sane NODE_ENV for third-party code.
+ */
+export declare const appEnvs: readonly ["development", "staging", "production", "test"];
+export type AppEnv = (typeof appEnvs)[number];
+export interface EnvironmentOptions {
+    /** App root — the directory containing `modules/` and `.envs/`. */
+    rootDir: string;
+    /** Override the mode; defaults to process.env.APP_ENV, then "development". */
+    appEnv?: AppEnv;
+    modulesDir?: string;
+    envsDir?: string;
+}
+/**
+ * Boot phases 1–3: load the mode's .env file, discover every module's
+ * meta.variables.json, resolve each declared variable with precedence
+ *
+ *   process.env  >  .envs/.env.<APP_ENV>  >  spec default
+ *
+ * (container-injected values must always win), validate everything, and
+ * crash once with the aggregate report if anything is missing or invalid.
+ */
+export declare class Environment {
+    #private;
+    readonly appEnv: AppEnv;
+    readonly store: VariableStore;
+    private constructor();
+    /**
+     * Convenience passthrough: `env.get("PORT")` ≡ `env.store.get("PORT")` —
+     * with per-variable types once `tulipes sync` has generated config.d.ts.
+     */
+    get<K extends string>(name: K): Resolved<K>;
+    static load(options: EnvironmentOptions): Environment;
+}
+export {};

package/dist/env/environment.js

@@ -0,0 +1,117 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { parse as parseDotenv } from "dotenv";
+import { BootReport } from "../errors/boot-error.js";
+import { coerceValue } from "./coerce.js";
+import { discoverModuleMeta } from "./meta-discovery.js";
+import { VariableStore } from "./variable-store.js";
+/**
+ * APP_ENV drives which .env file loads. It is deliberately NOT NODE_ENV:
+ * bundlers and libraries overload NODE_ENV as an optimization flag, so Tulipes
+ * keeps its own axis and mirrors a sane NODE_ENV for third-party code.
+ */
+export const appEnvs = ["development", "staging", "production", "test"];
+/**
+ * Boot phases 1–3: load the mode's .env file, discover every module's
+ * meta.variables.json, resolve each declared variable with precedence
+ *
+ *   process.env  >  .envs/.env.<APP_ENV>  >  spec default
+ *
+ * (container-injected values must always win), validate everything, and
+ * crash once with the aggregate report if anything is missing or invalid.
+ */
+export class Environment {
+    appEnv;
+    store;
+    constructor(appEnv, store) {
+        this.appEnv = appEnv;
+        this.store = store;
+    }
+    /**
+     * Convenience passthrough: `env.get("PORT")` ≡ `env.store.get("PORT")` —
+     * with per-variable types once `tulipes sync` has generated config.d.ts.
+     */
+    get(name) {
+        return this.store.get(name);
+    }
+    static load(options) {
+        const report = new BootReport();
+        const appEnv = Environment.#resolveAppEnv(options.appEnv, report);
+        // Mirror NODE_ENV for third-party libs: anything that isn't clearly
+        // dev/test should get production-grade behavior from them.
+        process.env.NODE_ENV ??=
+            appEnv === "development" || appEnv === "test" ? appEnv : "production";
+        const envsDir = options.envsDir ?? join(options.rootDir, ".envs");
+        const modulesDir = options.modulesDir ?? join(options.rootDir, "modules");
+        const fileValues = Environment.#readEnvFile(join(envsDir, `.env.${appEnv}`));
+        const metas = discoverModuleMeta(modulesDir, report);
+        const store = new VariableStore();
+        Environment.#resolveAll(metas, fileValues, store, report);
+        report.throwIfAny("environment");
+        return new Environment(appEnv, store);
+    }
+    static #resolveAppEnv(override, report) {
+        const raw = override ?? process.env.APP_ENV ?? "development";
+        if (appEnvs.includes(raw))
+            return raw;
+        report.add({
+            scope: "env",
+            message: `APP_ENV "${raw}" is invalid — expected one of: ${appEnvs.join(", ")}`,
+        });
+        return "development"; // placeholder; the report will crash the boot anyway
+    }
+    /**
+     * A missing file is not an error: production containers typically inject
+     * everything through real environment variables and ship no .env at all.
+     */
+    static #readEnvFile(filePath) {
+        try {
+            return parseDotenv(readFileSync(filePath, "utf8"));
+        }
+        catch {
+            return {};
+        }
+    }
+    static #resolveAll(metas, fileValues, store, report) {
+        // Every variable has exactly one owning module. Shared infra variables
+        // (MONGO_URI, PORT…) belong to the sys core module; everyone else reads.
+        const owners = new Map();
+        for (const meta of metas) {
+            for (const spec of meta.variables) {
+                const existingOwner = owners.get(spec.name);
+                if (existingOwner) {
+                    report.add({
+                        scope: "env",
+                        module: meta.module,
+                        message: `variable "${spec.name}" is already declared by module "${existingOwner}" — one owner per variable`,
+                    });
+                    continue;
+                }
+                owners.set(spec.name, meta.module);
+                const raw = process.env[spec.name] ?? fileValues[spec.name] ?? spec.default;
+                if (raw === undefined) {
+                    if (spec.required) {
+                        report.add({
+                            scope: "env",
+                            module: meta.module,
+                            message: `required variable "${spec.name}" has no value (${spec.description})`,
+                        });
+                    }
+                    // Optional without default: legitimately absent, nothing to store.
+                    continue;
+                }
+                const coerced = coerceValue(spec, raw);
+                if (!coerced.ok) {
+                    report.add({
+                        scope: "env",
+                        module: meta.module,
+                        message: `variable "${spec.name}": ${coerced.reason}`,
+                    });
+                    continue;
+                }
+                store.declare_(spec, meta.module, coerced.value);
+            }
+        }
+    }
+}
+//# sourceMappingURL=environment.js.map

package/dist/env/environment.js.map

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

package/dist/env/index.d.ts

@@ -0,0 +1,14 @@
+export { Environment, appEnvs, type AppEnv, type EnvironmentOptions } from "./environment.js";
+/**
+ * Augmentation target for the generated `types/config.d.ts` (`tulipes sync`):
+ * one property per declared variable, typed from its meta spec. Empty here on
+ * purpose — an app without codegen still gets `VariableValue` from get().
+ *
+ * Declared in THIS module (not re-exported) because TypeScript module
+ * augmentation only merges with the module that declares the interface.
+ */
+export interface KnownVariables {
+}
+export { VariableStore } from "./variable-store.js";
+export { discoverModuleMeta, META_FILENAME, type ModuleMeta } from "./meta-discovery.js";
+export { metaFileSchema, variableSpecSchema, variableTypes, type MetaFile, type VariableSpec, type VariableType, type VariableValue, } from "./spec.js";

package/dist/env/index.js

@@ -0,0 +1,5 @@
+export { Environment, appEnvs } from "./environment.js";
+export { VariableStore } from "./variable-store.js";
+export { discoverModuleMeta, META_FILENAME } from "./meta-discovery.js";
+export { metaFileSchema, variableSpecSchema, variableTypes, } from "./spec.js";
+//# sourceMappingURL=index.js.map

package/dist/env/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/env/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,OAAO,EAAwC,MAAM,kBAAkB,CAAC;AAW9F,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,kBAAkB,EAAE,aAAa,EAAmB,MAAM,qBAAqB,CAAC;AACzF,OAAO,EACL,cAAc,EACd,kBAAkB,EAClB,aAAa,GAKd,MAAM,WAAW,CAAC"}

package/dist/env/meta-discovery.d.ts

@@ -0,0 +1,17 @@
+import { BootReport } from "../errors/boot-error.js";
+import { type VariableSpec } from "./spec.js";
+export declare const META_FILENAME = "meta.variables.json";
+export interface ModuleMeta {
+    /** Folder name under modules/ — enough for attribution at this phase. */
+    module: string;
+    filePath: string;
+    variables: VariableSpec[];
+}
+/**
+ * Walk `modules/*` and load every module's env contract.
+ *
+ * A module without a meta file simply declares no variables — that's valid,
+ * not an error. Malformed files, on the other hand, are collected into the
+ * report (never thrown one-by-one) so the developer sees all of them at once.
+ */
+export declare function discoverModuleMeta(modulesDir: string, report: BootReport): ModuleMeta[];

package/dist/env/meta-discovery.js

@@ -0,0 +1,65 @@
+import { readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { BootReport } from "../errors/boot-error.js";
+import { metaFileSchema } from "./spec.js";
+export const META_FILENAME = "meta.variables.json";
+/**
+ * Walk `modules/*` and load every module's env contract.
+ *
+ * A module without a meta file simply declares no variables — that's valid,
+ * not an error. Malformed files, on the other hand, are collected into the
+ * report (never thrown one-by-one) so the developer sees all of them at once.
+ */
+export function discoverModuleMeta(modulesDir, report) {
+    let entries;
+    try {
+        entries = readdirSync(modulesDir, { withFileTypes: true });
+    }
+    catch {
+        report.add({
+            scope: "env",
+            message: `modules directory not found: ${modulesDir}`,
+        });
+        return [];
+    }
+    const metas = [];
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        const module = entry.name;
+        const filePath = join(modulesDir, module, META_FILENAME);
+        let text;
+        try {
+            text = readFileSync(filePath, "utf8");
+        }
+        catch {
+            continue; // no meta file — module needs no env variables
+        }
+        let json;
+        try {
+            json = JSON.parse(text);
+        }
+        catch (error) {
+            report.add({
+                scope: "env",
+                module,
+                message: `${META_FILENAME} is not valid JSON: ${error.message}`,
+            });
+            continue;
+        }
+        const parsed = metaFileSchema.safeParse(json);
+        if (!parsed.success) {
+            for (const issue of parsed.error.issues) {
+                report.add({
+                    scope: "env",
+                    module,
+                    message: `${META_FILENAME}: ${issue.message}`,
+                });
+            }
+            continue;
+        }
+        metas.push({ module, filePath, variables: parsed.data.variables });
+    }
+    return metas;
+}
+//# sourceMappingURL=meta-discovery.js.map

package/dist/env/meta-discovery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"meta-discovery.js","sourceRoot":"","sources":["../../src/env/meta-discovery.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACpD,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AACrD,OAAO,EAAE,cAAc,EAAqB,MAAM,WAAW,CAAC;AAE9D,MAAM,CAAC,MAAM,aAAa,GAAG,qBAAqB,CAAC;AASnD;;;;;;GAMG;AACH,MAAM,UAAU,kBAAkB,CAChC,UAAkB,EAClB,MAAkB;IAElB,IAAI,OAAO,CAAC;IACZ,IAAI,CAAC;QACH,OAAO,GAAG,WAAW,CAAC,UAAU,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC;IAC7D,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,CAAC,GAAG,CAAC;YACT,KAAK,EAAE,KAAK;YACZ,OAAO,EAAE,gCAAgC,UAAU,EAAE;SACtD,CAAC,CAAC;QACH,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,MAAM,KAAK,GAAiB,EAAE,CAAC;IAE/B,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,IAAI,CAAC,KAAK,CAAC,WAAW,EAAE;YAAE,SAAS;QACnC,MAAM,MAAM,GAAG,KAAK,CAAC,IAAI,CAAC;QAC1B,MAAM,QAAQ,GAAG,IAAI,CAAC,UAAU,EAAE,MAAM,EAAE,aAAa,CAAC,CAAC;QAEzD,IAAI,IAAY,CAAC;QACjB,IAAI,CAAC;YACH,IAAI,GAAG,YAAY,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;QACxC,CAAC;QAAC,MAAM,CAAC;YACP,SAAS,CAAC,+CAA+C;QAC3D,CAAC;QAED,IAAI,IAAa,CAAC;QAClB,IAAI,CAAC;YACH,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAC1B,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,CAAC,GAAG,CAAC;gBACT,KAAK,EAAE,KAAK;gBACZ,MAAM;gBACN,OAAO,EAAE,GAAG,aAAa,uBAAwB,KAAe,CAAC,OAAO,EAAE;aAC3E,CAAC,CAAC;YACH,SAAS;QACX,CAAC;QAED,MAAM,MAAM,GAAG,cAAc,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;QAC9C,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;YACpB,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC;gBACxC,MAAM,CAAC,GAAG,CAAC;oBACT,KAAK,EAAE,KAAK;oBACZ,MAAM;oBACN,OAAO,EAAE,GAAG,aAAa,KAAK,KAAK,CAAC,OAAO,EAAE;iBAC9C,CAAC,CAAC;YACL,CAAC;YACD,SAAS;QACX,CAAC;QAED,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC,CAAC;IACrE,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC"}