@tulipes/core 0.1.0

package/dist/modules/explorer.js

@@ -0,0 +1,64 @@
+import { existsSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+/**
+ * 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 function detectSourceExtension() {
+    const self = fileURLToPath(import.meta.url);
+    if (self.endsWith(".ts"))
+        return ".ts";
+    if (!existsSync(self) && existsSync(self.replace(/\.js$/, ".ts")))
+        return ".ts";
+    return ".js";
+}
+/** dir name → file suffix, e.g. routes/users.routes.ts */
+const COLLECTIONS = [
+    ["routeFiles", "routes", ".routes"],
+    ["modelFiles", "models", ".model"],
+    ["bootstrapFiles", "bootstrap", ".bootstrap"],
+    ["queueFiles", "queues", ".queues"],
+    ["socketFiles", "sockets", ".sockets"],
+];
+export function exploreModules(modules, options = {}) {
+    const ext = options.sourceExtension ?? detectSourceExtension();
+    return modules.map((module) => {
+        const files = {
+            module,
+            routeFiles: [],
+            modelFiles: [],
+            bootstrapFiles: [],
+            queueFiles: [],
+            socketFiles: [],
+        };
+        const configFile = join(module.dir, `module.config${ext}`);
+        if (existsSync(configFile))
+            files.configFile = configFile;
+        const aclFile = join(module.dir, `module.acl${ext}`);
+        if (existsSync(aclFile))
+            files.aclFile = aclFile;
+        for (const [key, dirName, suffix] of COLLECTIONS) {
+            files[key] = listWithSuffix(join(module.dir, dirName), suffix + ext);
+        }
+        return files;
+    });
+}
+function listWithSuffix(dir, suffix) {
+    let entries;
+    try {
+        entries = readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return []; // directory absent — the module doesn't use this feature
+    }
+    return entries
+        .filter((entry) => entry.isFile() && entry.name.endsWith(suffix))
+        .map((entry) => join(dir, entry.name))
+        .sort(); // deterministic order within a module
+}
+//# sourceMappingURL=explorer.js.map

package/dist/modules/explorer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"explorer.js","sourceRoot":"","sources":["../../src/modules/explorer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAClD,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAiBzC;;;;;;;GAOG;AACH,MAAM,UAAU,qBAAqB;IACnC,MAAM,IAAI,GAAG,aAAa,CAAC,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC;IAC5C,IAAI,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IACvC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,UAAU,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;QAAE,OAAO,KAAK,CAAC;IAChF,OAAO,KAAK,CAAC;AACf,CAAC;AAeD,0DAA0D;AAC1D,MAAM,WAAW,GAAG;IAClB,CAAC,YAAY,EAAE,QAAQ,EAAE,SAAS,CAAC;IACnC,CAAC,YAAY,EAAE,QAAQ,EAAE,QAAQ,CAAC;IAClC,CAAC,gBAAgB,EAAE,WAAW,EAAE,YAAY,CAAC;IAC7C,CAAC,YAAY,EAAE,QAAQ,EAAE,SAAS,CAAC;IACnC,CAAC,aAAa,EAAE,SAAS,EAAE,UAAU,CAAC;CAC9B,CAAC;AAOX,MAAM,UAAU,cAAc,CAC5B,OAAkC,EAClC,OAAO,GAAmB,EAAE;IAE5B,MAAM,GAAG,GAAG,OAAO,CAAC,eAAe,IAAI,qBAAqB,EAAE,CAAC;IAE/D,OAAO,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE;QAC5B,MAAM,KAAK,GAAgB;YACzB,MAAM;YACN,UAAU,EAAE,EAAE;YACd,UAAU,EAAE,EAAE;YACd,cAAc,EAAE,EAAE;YAClB,UAAU,EAAE,EAAE;YACd,WAAW,EAAE,EAAE;SAChB,CAAC;QAEF,MAAM,UAAU,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,EAAE,gBAAgB,GAAG,EAAE,CAAC,CAAC;QAC3D,IAAI,UAAU,CAAC,UAAU,CAAC;YAAE,KAAK,CAAC,UAAU,GAAG,UAAU,CAAC;QAE1D,MAAM,OAAO,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,EAAE,aAAa,GAAG,EAAE,CAAC,CAAC;QACrD,IAAI,UAAU,CAAC,OAAO,CAAC;YAAE,KAAK,CAAC,OAAO,GAAG,OAAO,CAAC;QAEjD,KAAK,MAAM,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,CAAC,IAAI,WAAW,EAAE,CAAC;YACjD,KAAK,CAAC,GAAG,CAAC,GAAG,cAAc,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,GAAG,CAAC,CAAC;QACvE,CAAC;QAED,OAAO,KAAK,CAAC;IACf,CAAC,CAAC,CAAC;AACL,CAAC;AAED,SAAS,cAAc,CAAC,GAAW,EAAE,MAAc;IACjD,IAAI,OAAO,CAAC;IACZ,IAAI,CAAC;QACH,OAAO,GAAG,WAAW,CAAC,GAAG,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC;IACtD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC,CAAC,yDAAyD;IACtE,CAAC;IACD,OAAO,OAAO;SACX,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,MAAM,EAAE,IAAI,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;SAChE,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;SACrC,IAAI,EAAE,CAAC,CAAC,sCAAsC;AACnD,CAAC"}

package/dist/modules/graph.d.ts

@@ -0,0 +1,16 @@
+import { BootReport } from "../errors/boot-error.js";
+import type { ModuleManifest } from "./manifest.js";
+/**
+ * Compute the definitive load order. Three sort keys, applied in order:
+ *
+ *   1. tier      — "sys" before "app"
+ *   2. priority  — lower first, tie-breaker within a tier
+ *   3. dependsOn — topological sort within the resulting order
+ *
+ * The topo sort is Kahn's algorithm, but ready modules are always picked in
+ * (tier, priority, name) order — that keeps the output deterministic AND
+ * guarantees the tier grouping holds: since a sys module may never depend on
+ * an app module, every sys module drains from the ready set before the first
+ * app module is picked.
+ */
+export declare function sortModules(modules: readonly ModuleManifest[], report: BootReport): ModuleManifest[];

package/dist/modules/graph.js

@@ -0,0 +1,80 @@
+import { BootReport } from "../errors/boot-error.js";
+/**
+ * Compute the definitive load order. Three sort keys, applied in order:
+ *
+ *   1. tier      — "sys" before "app"
+ *   2. priority  — lower first, tie-breaker within a tier
+ *   3. dependsOn — topological sort within the resulting order
+ *
+ * The topo sort is Kahn's algorithm, but ready modules are always picked in
+ * (tier, priority, name) order — that keeps the output deterministic AND
+ * guarantees the tier grouping holds: since a sys module may never depend on
+ * an app module, every sys module drains from the ready set before the first
+ * app module is picked.
+ */
+export function sortModules(modules, report) {
+    const byName = new Map(modules.map((m) => [m.name, m]));
+    let valid = true;
+    for (const module of modules) {
+        for (const dep of module.dependsOn) {
+            const target = byName.get(dep);
+            if (!target) {
+                report.add({
+                    scope: "modules",
+                    module: module.name,
+                    message: `dependsOn "${dep}" — no such module exists`,
+                });
+                valid = false;
+            }
+            else if (module.tier === "sys" && target.tier === "app") {
+                report.add({
+                    scope: "modules",
+                    module: module.name,
+                    message: `sys module cannot depend on app module "${dep}" — sys loads first by definition`,
+                });
+                valid = false;
+            }
+        }
+    }
+    // Broken edges make any order meaningless; skip the sort, the report
+    // already carries the reason boot will abort.
+    if (!valid)
+        return [];
+    const presorted = [...modules].sort((a, b) => Number(a.tier === "app") - Number(b.tier === "app") ||
+        a.priority - b.priority ||
+        a.name.localeCompare(b.name));
+    const blockers = new Map(modules.map((m) => [m.name, new Set(m.dependsOn)]));
+    const order = [];
+    const placed = new Set();
+    while (order.length < modules.length) {
+        const next = presorted.find((m) => !placed.has(m.name) && blockers.get(m.name).size === 0);
+        if (!next) {
+            report.add({
+                scope: "modules",
+                message: `dependency cycle: ${describeCycle(modules, blockers)}`,
+            });
+            return [];
+        }
+        order.push(next);
+        placed.add(next.name);
+        for (const remaining of blockers.values())
+            remaining.delete(next.name);
+    }
+    return order;
+}
+/**
+ * When Kahn stalls, every unplaced module still has a blocker — walking
+ * first-blockers from any of them must eventually revisit a node. That loop
+ * is the cycle we print (e.g. "auth → users → auth").
+ */
+function describeCycle(modules, blockers) {
+    const start = modules.find((m) => blockers.get(m.name).size > 0).name;
+    const path = [];
+    let current = start;
+    while (!path.includes(current)) {
+        path.push(current);
+        current = blockers.get(current).values().next().value;
+    }
+    return [...path.slice(path.indexOf(current)), current].join(" → ");
+}
+//# sourceMappingURL=graph.js.map

package/dist/modules/graph.js.map

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

package/dist/modules/index.d.ts

@@ -0,0 +1,4 @@
+export { discoverModules } from "./discovery.js";
+export { detectSourceExtension, exploreModules, type ExploreOptions, type ModuleFiles, type SourceExtension, } from "./explorer.js";
+export { sortModules } from "./graph.js";
+export { DEFAULT_PRIORITY, tulipesManifestSchema, moduleTiers, type ModuleManifest, type ModuleTier, } from "./manifest.js";

package/dist/modules/index.js

@@ -0,0 +1,5 @@
+export { discoverModules } from "./discovery.js";
+export { detectSourceExtension, exploreModules, } from "./explorer.js";
+export { sortModules } from "./graph.js";
+export { DEFAULT_PRIORITY, tulipesManifestSchema, moduleTiers, } from "./manifest.js";
+//# sourceMappingURL=index.js.map

package/dist/modules/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/modules/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACjD,OAAO,EACL,qBAAqB,EACrB,cAAc,GAIf,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACzC,OAAO,EACL,gBAAgB,EAChB,qBAAqB,EACrB,WAAW,GAGZ,MAAM,eAAe,CAAC"}

package/dist/modules/manifest.d.ts

@@ -0,0 +1,43 @@
+import { z } from "zod";
+/**
+ * A module's ordering metadata lives under the "tulipes" key of its
+ * package.json — never in the folder name — so reprioritizing a module can
+ * never break the `dependsOn` references pointing at it.
+ */
+export declare const moduleTiers: readonly [
+/** Framework-critical modules; always load before every "app" module. */
+"sys", "app"];
+export type ModuleTier = (typeof moduleTiers)[number];
+export declare const DEFAULT_PRIORITY = 100;
+/**
+ * `.strict()` so a typo like "dependson" crashes boot instead of silently
+ * loading the module with default ordering.
+ */
+export declare const tulipesManifestSchema: z.ZodObject<{
+    tier: z.ZodDefault<z.ZodEnum<["sys", "app"]>>;
+    /** Lower loads earlier; tie-breaker inside a tier. */
+    priority: z.ZodDefault<z.ZodNumber>;
+    /** Short names of modules that must load before this one. */
+    dependsOn: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+}, "strict", z.ZodTypeAny, {
+    tier: "app" | "sys";
+    priority: number;
+    dependsOn: string[];
+}, {
+    tier?: "app" | "sys" | undefined;
+    priority?: number | undefined;
+    dependsOn?: string[] | undefined;
+}>;
+export interface ModuleManifest {
+    /**
+     * Canonical short name — the last segment of the package name
+     * (`@app/users` → `users`). This is what `dependsOn` references.
+     */
+    name: string;
+    packageName: string;
+    /** Absolute path to the module's folder. */
+    dir: string;
+    tier: ModuleTier;
+    priority: number;
+    dependsOn: readonly string[];
+}

package/dist/modules/manifest.js

@@ -0,0 +1,26 @@
+import { z } from "zod";
+/**
+ * A module's ordering metadata lives under the "tulipes" key of its
+ * package.json — never in the folder name — so reprioritizing a module can
+ * never break the `dependsOn` references pointing at it.
+ */
+export const moduleTiers = [
+    /** Framework-critical modules; always load before every "app" module. */
+    "sys",
+    "app",
+];
+export const DEFAULT_PRIORITY = 100;
+/**
+ * `.strict()` so a typo like "dependson" crashes boot instead of silently
+ * loading the module with default ordering.
+ */
+export const tulipesManifestSchema = z
+    .object({
+    tier: z.enum(moduleTiers).default("app"),
+    /** Lower loads earlier; tie-breaker inside a tier. */
+    priority: z.number().int().default(DEFAULT_PRIORITY),
+    /** Short names of modules that must load before this one. */
+    dependsOn: z.array(z.string().min(1)).default([]),
+})
+    .strict();
+//# sourceMappingURL=manifest.js.map

package/dist/modules/manifest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.js","sourceRoot":"","sources":["../../src/modules/manifest.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;GAIG;AAEH,MAAM,CAAC,MAAM,WAAW,GAAG;IACzB,yEAAyE;IACzE,KAAK;IACL,KAAK;CACG,CAAC;AAIX,MAAM,CAAC,MAAM,gBAAgB,GAAG,GAAG,CAAC;AAEpC;;;GAGG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC;KACnC,MAAM,CAAC;IACN,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC;IACxC,sDAAsD;IACtD,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,gBAAgB,CAAC;IACpD,6DAA6D;IAC7D,SAAS,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC;CAClD,CAAC;KACD,MAAM,EAAE,CAAC"}

package/dist/queues/index.d.ts

@@ -0,0 +1,2 @@
+export { QueueManager, QueueRegistry } from "./queue-manager.js";
+export { initQueues, type QueuesFn } from "./load-queues.js";

package/dist/queues/index.js

@@ -0,0 +1,3 @@
+export { QueueManager, QueueRegistry } from "./queue-manager.js";
+export { initQueues } from "./load-queues.js";
+//# sourceMappingURL=index.js.map

package/dist/queues/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/queues/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACjE,OAAO,EAAE,UAAU,EAAiB,MAAM,kBAAkB,CAAC"}

package/dist/queues/load-queues.d.ts

@@ -0,0 +1,12 @@
+import { BootReport } from "../errors/boot-error.js";
+import type { Ctx } from "../boot/contracts.js";
+import type { ModuleFiles } from "../modules/explorer.js";
+import { QueueManager, type QueueRegistry } from "./queue-manager.js";
+/** Default export of `queues/*.queues.ts`. */
+export type QueuesFn = (ctx: Ctx, queues: QueueRegistry) => void | Promise<void>;
+/**
+ * Phase 9: run every `*.queues.ts` in load order. Same skip/refuse logic as
+ * the database: a queue-less app is fine, queue files without REDIS_URL are
+ * a contradiction.
+ */
+export declare function initQueues(explored: readonly ModuleFiles[], ctx: Ctx, report: BootReport): Promise<QueueManager | undefined>;

package/dist/queues/load-queues.js

@@ -0,0 +1,56 @@
+import { BootReport } from "../errors/boot-error.js";
+import { importFile } from "../boot/import-file.js";
+import { QueueManager } from "./queue-manager.js";
+/** Well-known infra variable, declared by the app's sys core module. */
+const REDIS_URL = "REDIS_URL";
+/**
+ * Phase 9: run every `*.queues.ts` in load order. Same skip/refuse logic as
+ * the database: a queue-less app is fine, queue files without REDIS_URL are
+ * a contradiction.
+ */
+export async function initQueues(explored, ctx, report) {
+    const hasQueueFiles = explored.some((files) => files.queueFiles.length > 0);
+    const url = ctx.Environment.store.has(REDIS_URL)
+        ? String(ctx.Environment.get(REDIS_URL))
+        : undefined;
+    if (!url) {
+        if (hasQueueFiles) {
+            report.add({
+                scope: "boot",
+                message: `modules declare queues but "${REDIS_URL}" is not declared/set — redis is required`,
+            });
+        }
+        return undefined;
+    }
+    if (!hasQueueFiles)
+        return undefined;
+    const manager = new QueueManager(url);
+    ctx.queues = manager;
+    for (const { module, queueFiles } of explored) {
+        for (const file of queueFiles) {
+            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 queues function (ctx, queues) => void`,
+                });
+                continue;
+            }
+            try {
+                await exported.default(ctx, manager.forModule(module.name, report));
+            }
+            catch (error) {
+                report.add({
+                    scope: "boot",
+                    module: module.name,
+                    message: `queues function threw: ${error.message}`,
+                });
+            }
+        }
+    }
+    return manager;
+}
+//# sourceMappingURL=load-queues.js.map

package/dist/queues/load-queues.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"load-queues.js","sourceRoot":"","sources":["../../src/queues/load-queues.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AACrD,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAGpD,OAAO,EAAE,YAAY,EAAsB,MAAM,oBAAoB,CAAC;AAKtE,wEAAwE;AACxE,MAAM,SAAS,GAAG,WAAW,CAAC;AAE9B;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAC9B,QAAgC,EAChC,GAAQ,EACR,MAAkB;IAElB,MAAM,aAAa,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,UAAU,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IAC5E,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,aAAa,EAAE,CAAC;YAClB,MAAM,CAAC,GAAG,CAAC;gBACT,KAAK,EAAE,MAAM;gBACb,OAAO,EAAE,+BAA+B,SAAS,2CAA2C;aAC7F,CAAC,CAAC;QACL,CAAC;QACD,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,IAAI,CAAC,aAAa;QAAE,OAAO,SAAS,CAAC;IAErC,MAAM,OAAO,GAAG,IAAI,YAAY,CAAC,GAAG,CAAC,CAAC;IACtC,GAAG,CAAC,MAAM,GAAG,OAAO,CAAC;IAErB,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,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,8DAA8D;iBAC/E,CAAC,CAAC;gBACH,SAAS;YACX,CAAC;YAED,IAAI,CAAC;gBACH,MAAO,QAAQ,CAAC,OAAoB,CAClC,GAAG,EACH,OAAO,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,CACvC,CAAC;YACJ,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,MAAM,CAAC,GAAG,CAAC;oBACT,KAAK,EAAE,MAAM;oBACb,MAAM,EAAE,MAAM,CAAC,IAAI;oBACnB,OAAO,EAAE,0BAA2B,KAAe,CAAC,OAAO,EAAE;iBAC9D,CAAC,CAAC;YACL,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/queues/queue-manager.d.ts

@@ -0,0 +1,44 @@
+import { Queue, type JobsOptions, type Processor, type QueueOptions, type WorkerOptions } from "bullmq";
+import { BootReport } from "../errors/boot-error.js";
+/**
+ * One manager owns every queue in the process. The same `*.queues.ts` files
+ * run in BOTH modes — definitions and processors are always registered — and
+ * the mode decides what happens with them:
+ *
+ *   web    → queues produce; processors are registered but never started
+ *   worker → `startWorkers()` turns every registered processor into a
+ *            consuming BullMQ Worker
+ *
+ * That symmetry is what lets a module describe its background work once.
+ */
+export declare class QueueManager {
+    #private;
+    constructor(redisUrl: string);
+    /** @internal Module-scoped facade for the loader. */
+    forModule(moduleName: string, report: BootReport): QueueRegistry;
+    /** @internal QueueRegistry only. */
+    define_(name: string, owner: string, options?: Partial<QueueOptions>): string | undefined;
+    /** @internal QueueRegistry only. */
+    process_(name: string, handler: Processor, owner: string, options?: Partial<WorkerOptions>): string | undefined;
+    /** Introspection for the startup banner and tooling. */
+    names(): string[];
+    get processorCount(): number;
+    get workerCount(): number;
+    /** Produce a job. The queue must have been defined by some module. */
+    add(queueName: string, jobName: string, data: unknown, options?: JobsOptions): Promise<void>;
+    queue(name: string): Queue;
+    /** Worker mode only — called by the boot driver, never by modules. */
+    startWorkers(report: BootReport): number;
+    /** Drain order: stop consuming, then producers, then raw connections. */
+    close(): Promise<void>;
+}
+/**
+ * Module-scoped facade handed to `*.queues.ts` — mirrors AclBuilder: every
+ * registration records its module so conflicts crash with both names.
+ */
+export declare class QueueRegistry {
+    #private;
+    constructor(manager: QueueManager, moduleName: string, report: BootReport);
+    define(name: string, options?: Partial<QueueOptions>): this;
+    process(name: string, handler: Processor, options?: Partial<WorkerOptions>): this;
+}

package/dist/queues/queue-manager.js

@@ -0,0 +1,134 @@
+import { Queue, Worker, } from "bullmq";
+import { Redis } from "ioredis";
+import { BootReport } from "../errors/boot-error.js";
+/**
+ * One manager owns every queue in the process. The same `*.queues.ts` files
+ * run in BOTH modes — definitions and processors are always registered — and
+ * the mode decides what happens with them:
+ *
+ *   web    → queues produce; processors are registered but never started
+ *   worker → `startWorkers()` turns every registered processor into a
+ *            consuming BullMQ Worker
+ *
+ * That symmetry is what lets a module describe its background work once.
+ */
+export class QueueManager {
+    #url;
+    #queues = new Map();
+    #processors = new Map();
+    #workers = [];
+    #connections = [];
+    constructor(redisUrl) {
+        this.#url = redisUrl;
+    }
+    /**
+     * Every BullMQ client gets its own connection: workers need dedicated
+     * blocking connections anyway, and never sharing keeps close() reasoning
+     * trivial. maxRetriesPerRequest: null is a BullMQ requirement.
+     */
+    #connect() {
+        const connection = new Redis(this.#url, { maxRetriesPerRequest: null });
+        this.#connections.push(connection);
+        return connection;
+    }
+    /** @internal Module-scoped facade for the loader. */
+    forModule(moduleName, report) {
+        return new QueueRegistry(this, moduleName, report);
+    }
+    /** @internal QueueRegistry only. */
+    define_(name, owner, options) {
+        const existing = this.#queues.get(name);
+        if (existing)
+            return existing.owner;
+        const queue = new Queue(name, { ...options, connection: this.#connect() });
+        this.#queues.set(name, { queue, owner });
+        return undefined;
+    }
+    /** @internal QueueRegistry only. */
+    process_(name, handler, owner, options) {
+        const existing = this.#processors.get(name);
+        if (existing)
+            return existing.owner;
+        this.#processors.set(name, { handler, owner, options });
+        return undefined;
+    }
+    /** Introspection for the startup banner and tooling. */
+    names() {
+        return [...this.#queues.keys()];
+    }
+    get processorCount() {
+        return this.#processors.size;
+    }
+    get workerCount() {
+        return this.#workers.length;
+    }
+    /** Produce a job. The queue must have been defined by some module. */
+    async add(queueName, jobName, data, options) {
+        await this.queue(queueName).add(jobName, data, options);
+    }
+    queue(name) {
+        const stored = this.#queues.get(name);
+        if (!stored) {
+            throw new Error(`Queue "${name}" was never defined by any module (known: ${[...this.#queues.keys()].join(", ") || "none"})`);
+        }
+        return stored.queue;
+    }
+    /** Worker mode only — called by the boot driver, never by modules. */
+    startWorkers(report) {
+        for (const [name, { handler, owner, options }] of this.#processors) {
+            if (!this.#queues.has(name)) {
+                report.add({
+                    scope: "boot",
+                    module: owner,
+                    message: `processor registered for undefined queue "${name}" — call define() first`,
+                });
+                continue;
+            }
+            this.#workers.push(new Worker(name, handler, { ...options, connection: this.#connect() }));
+        }
+        return this.#workers.length;
+    }
+    /** Drain order: stop consuming, then producers, then raw connections. */
+    async close() {
+        await Promise.all(this.#workers.map((worker) => worker.close()));
+        await Promise.all([...this.#queues.values()].map(({ queue }) => queue.close()));
+        await Promise.all(this.#connections.map((connection) => connection.quit().catch(() => { })));
+    }
+}
+// BullMQ reserves ":" (its redis key separator), so module namespacing in
+// queue names uses "." instead: "users.welcome".
+const QUEUE_NAME = /^[a-z0-9-]+(\.[a-z0-9-]+)?$/;
+/**
+ * Module-scoped facade handed to `*.queues.ts` — mirrors AclBuilder: every
+ * registration records its module so conflicts crash with both names.
+ */
+export class QueueRegistry {
+    #manager;
+    #module;
+    #report;
+    constructor(manager, moduleName, report) {
+        this.#manager = manager;
+        this.#module = moduleName;
+        this.#report = report;
+    }
+    define(name, options) {
+        if (!QUEUE_NAME.test(name)) {
+            this.#issue(`queue name "${name}" is invalid — lowercase kebab-case, optional "." namespace`);
+            return this;
+        }
+        const owner = this.#manager.define_(name, this.#module, options);
+        if (owner)
+            this.#issue(`queue "${name}" is already defined by module "${owner}"`);
+        return this;
+    }
+    process(name, handler, options) {
+        const owner = this.#manager.process_(name, handler, this.#module, options);
+        if (owner)
+            this.#issue(`queue "${name}" already has a processor from module "${owner}"`);
+        return this;
+    }
+    #issue(message) {
+        this.#report.add({ scope: "boot", module: this.#module, message });
+    }
+}
+//# sourceMappingURL=queue-manager.js.map

package/dist/queues/queue-manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"queue-manager.js","sourceRoot":"","sources":["../../src/queues/queue-manager.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,EACL,MAAM,GAKP,MAAM,QAAQ,CAAC;AAChB,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAEhC,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAErD;;;;;;;;;;GAUG;AACH,MAAM,OAAO,YAAY;IACd,IAAI,CAAS;IACb,OAAO,GAAG,IAAI,GAAG,EAA2C,CAAC;IAC7D,WAAW,GAAG,IAAI,GAAG,EAG3B,CAAC;IACK,QAAQ,GAAa,EAAE,CAAC;IACxB,YAAY,GAAY,EAAE,CAAC;IAEpC,YAAY,QAAgB;QAC1B,IAAI,CAAC,IAAI,GAAG,QAAQ,CAAC;IACvB,CAAC;IAED;;;;OAIG;IACH,QAAQ;QACN,MAAM,UAAU,GAAG,IAAI,KAAK,CAAC,IAAI,CAAC,IAAI,EAAE,EAAE,oBAAoB,EAAE,IAAI,EAAE,CAAC,CAAC;QACxE,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;QACnC,OAAO,UAAU,CAAC;IACpB,CAAC;IAED,qDAAqD;IACrD,SAAS,CAAC,UAAkB,EAAE,MAAkB;QAC9C,OAAO,IAAI,aAAa,CAAC,IAAI,EAAE,UAAU,EAAE,MAAM,CAAC,CAAC;IACrD,CAAC;IAED,oCAAoC;IACpC,OAAO,CACL,IAAY,EACZ,KAAa,EACb,OAA+B;QAE/B,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACxC,IAAI,QAAQ;YAAE,OAAO,QAAQ,CAAC,KAAK,CAAC;QACpC,MAAM,KAAK,GAAG,IAAI,KAAK,CAAC,IAAI,EAAE,EAAE,GAAG,OAAO,EAAE,UAAU,EAAE,IAAI,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;QAC3E,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;QACzC,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,oCAAoC;IACpC,QAAQ,CACN,IAAY,EACZ,OAAkB,EAClB,KAAa,EACb,OAAgC;QAEhC,MAAM,QAAQ,GAAG,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAC5C,IAAI,QAAQ;YAAE,OAAO,QAAQ,CAAC,KAAK,CAAC;QACpC,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,IAAI,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC,CAAC;QACxD,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,wDAAwD;IACxD,KAAK;QACH,OAAO,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC;IAClC,CAAC;IAED,IAAI,cAAc;QAChB,OAAO,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC;IAC/B,CAAC;IAED,IAAI,WAAW;QACb,OAAO,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC;IAC9B,CAAC;IAED,sEAAsE;IACtE,KAAK,CAAC,GAAG,CACP,SAAiB,EACjB,OAAe,EACf,IAAa,EACb,OAAqB;QAErB,MAAM,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,GAAG,CAAC,OAAO,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC;IAC1D,CAAC;IAED,KAAK,CAAC,IAAY;QAChB,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,6CAA6C,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,MAAM,GAAG,CAC5G,CAAC;QACJ,CAAC;QACD,OAAO,MAAM,CAAC,KAAK,CAAC;IACtB,CAAC;IAED,sEAAsE;IACtE,YAAY,CAAC,MAAkB;QAC7B,KAAK,MAAM,CAAC,IAAI,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC;YACnE,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;gBAC5B,MAAM,CAAC,GAAG,CAAC;oBACT,KAAK,EAAE,MAAM;oBACb,MAAM,EAAE,KAAK;oBACb,OAAO,EAAE,6CAA6C,IAAI,yBAAyB;iBACpF,CAAC,CAAC;gBACH,SAAS;YACX,CAAC;YACD,IAAI,CAAC,QAAQ,CAAC,IAAI,CAChB,IAAI,MAAM,CAAC,IAAI,EAAE,OAAO,EAAE,EAAE,GAAG,OAAO,EAAE,UAAU,EAAE,IAAI,CAAC,QAAQ,EAAE,EAAE,CAAC,CACvE,CAAC;QACJ,CAAC;QACD,OAAO,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC;IAC9B,CAAC;IAED,yEAAyE;IACzE,KAAK,CAAC,KAAK;QACT,MAAM,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;QACjE,MAAM,OAAO,CAAC,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;QAChF,MAAM,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC,UAAU,EAAE,EAAE,CAAC,UAAU,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC,CAAC,CAAC;IAC9F,CAAC;CACF;AAED,0EAA0E;AAC1E,iDAAiD;AACjD,MAAM,UAAU,GAAG,6BAA6B,CAAC;AAEjD;;;GAGG;AACH,MAAM,OAAO,aAAa;IACf,QAAQ,CAAe;IACvB,OAAO,CAAS;IAChB,OAAO,CAAa;IAE7B,YAAY,OAAqB,EAAE,UAAkB,EAAE,MAAkB;QACvE,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC;QACxB,IAAI,CAAC,OAAO,GAAG,UAAU,CAAC;QAC1B,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC;IACxB,CAAC;IAED,MAAM,CAAC,IAAY,EAAE,OAA+B;QAClD,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;YAC3B,IAAI,CAAC,MAAM,CAAC,eAAe,IAAI,6DAA6D,CAAC,CAAC;YAC9F,OAAO,IAAI,CAAC;QACd,CAAC;QACD,MAAM,KAAK,GAAG,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACjE,IAAI,KAAK;YAAE,IAAI,CAAC,MAAM,CAAC,UAAU,IAAI,mCAAmC,KAAK,GAAG,CAAC,CAAC;QAClF,OAAO,IAAI,CAAC;IACd,CAAC;IAED,OAAO,CAAC,IAAY,EAAE,OAAkB,EAAE,OAAgC;QACxE,MAAM,KAAK,GAAG,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QAC3E,IAAI,KAAK;YAAE,IAAI,CAAC,MAAM,CAAC,UAAU,IAAI,0CAA0C,KAAK,GAAG,CAAC,CAAC;QACzF,OAAO,IAAI,CAAC;IACd,CAAC;IAED,MAAM,CAAC,OAAe;QACpB,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,OAAO,EAAE,OAAO,EAAE,CAAC,CAAC;IACrE,CAAC;CACF"}

package/dist/sockets/index.d.ts

@@ -0,0 +1,2 @@
+export { SocketManager, SocketRegistry } from "./socket-manager.js";
+export { initSockets, type SocketsFn } from "./load-sockets.js";

package/dist/sockets/index.js

@@ -0,0 +1,3 @@
+export { SocketManager, SocketRegistry } from "./socket-manager.js";
+export { initSockets } from "./load-sockets.js";
+//# sourceMappingURL=index.js.map

package/dist/sockets/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/sockets/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACpE,OAAO,EAAE,WAAW,EAAkB,MAAM,mBAAmB,CAAC"}

package/dist/sockets/load-sockets.d.ts

@@ -0,0 +1,13 @@
+import type { Server as HttpServer } from "node:http";
+import { BootReport } from "../errors/boot-error.js";
+import type { Ctx } from "../boot/contracts.js";
+import type { ModuleFiles } from "../modules/explorer.js";
+import { SocketManager, type SocketRegistry } from "./socket-manager.js";
+/** Default export of `sockets/*.sockets.ts` (web branch only). */
+export type SocketsFn = (ctx: Ctx, sockets: SocketRegistry) => void | Promise<void>;
+/**
+ * Phase 11w: attach Socket.IO to the http server and run every
+ * `*.sockets.ts` in load order. No socket files → no Socket.IO server at
+ * all; websockets are opt-in per app, not a standing cost.
+ */
+export declare function initSockets(explored: readonly ModuleFiles[], ctx: Ctx, httpServer: HttpServer, report: BootReport): Promise<SocketManager | undefined>;

package/dist/sockets/load-sockets.js

@@ -0,0 +1,42 @@
+import { BootReport } from "../errors/boot-error.js";
+import { importFile } from "../boot/import-file.js";
+import { SocketManager } from "./socket-manager.js";
+/**
+ * Phase 11w: attach Socket.IO to the http server and run every
+ * `*.sockets.ts` in load order. No socket files → no Socket.IO server at
+ * all; websockets are opt-in per app, not a standing cost.
+ */
+export async function initSockets(explored, ctx, httpServer, report) {
+    if (!explored.some((files) => files.socketFiles.length > 0)) {
+        return undefined;
+    }
+    const manager = new SocketManager(httpServer);
+    ctx.sockets = manager;
+    for (const { module, socketFiles } of explored) {
+        for (const file of socketFiles) {
+            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 sockets function (ctx, sockets) => void`,
+                });
+                continue;
+            }
+            try {
+                await exported.default(ctx, manager.forModule(module.name, report));
+            }
+            catch (error) {
+                report.add({
+                    scope: "boot",
+                    module: module.name,
+                    message: `sockets function threw: ${error.message}`,
+                });
+            }
+        }
+    }
+    return manager;
+}
+//# sourceMappingURL=load-sockets.js.map

package/dist/sockets/load-sockets.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"load-sockets.js","sourceRoot":"","sources":["../../src/sockets/load-sockets.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AACrD,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAGpD,OAAO,EAAE,aAAa,EAAuB,MAAM,qBAAqB,CAAC;AAKzE;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,QAAgC,EAChC,GAAQ,EACR,UAAsB,EACtB,MAAkB;IAElB,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,WAAW,CAAC,MAAM,GAAG,CAAC,CAAC,EAAE,CAAC;QAC5D,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,MAAM,OAAO,GAAG,IAAI,aAAa,CAAC,UAAU,CAAC,CAAC;IAC9C,GAAG,CAAC,OAAO,GAAG,OAAO,CAAC;IAEtB,KAAK,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,IAAI,QAAQ,EAAE,CAAC;QAC/C,KAAK,MAAM,IAAI,IAAI,WAAW,EAAE,CAAC;YAC/B,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,gEAAgE;iBACjF,CAAC,CAAC;gBACH,SAAS;YACX,CAAC;YAED,IAAI,CAAC;gBACH,MAAO,QAAQ,CAAC,OAAqB,CACnC,GAAG,EACH,OAAO,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,CACvC,CAAC;YACJ,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,MAAM,CAAC,GAAG,CAAC;oBACT,KAAK,EAAE,MAAM;oBACb,MAAM,EAAE,MAAM,CAAC,IAAI;oBACnB,OAAO,EAAE,2BAA4B,KAAe,CAAC,OAAO,EAAE;iBAC/D,CAAC,CAAC;YACL,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC"}