@gettersethya/mira 0.1.0-alpha.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Getter Sethya
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/src/app/app.d.ts

@@ -0,0 +1,96 @@
+import { HttpServer } from "@effect/platform";
+import { Layer } from "effect";
+import { Migrator } from "../migrator/migrator.js";
+import { AppConfig } from "../config/index.js";
+import type { MiraAppConfig } from "./builder.js";
+/**
+ * The assembled Mira application, ready to serve.
+ *
+ * Created by `MiraBuilder.build()`. Do not construct directly — use the
+ * `Mira.builder()` fluent API.
+ *
+ * `MiraApp` wires all layers (database, storage, collection service, HTTP server,
+ * telemetry, auto-migration) and provides `serve()` to start the server.
+ * Use `extend()` to add custom layers before serving.
+ *
+ * @example
+ * const app = Mira.builder()
+ *   .platform(NodePlatform)
+ *   .database(SqliteDatabase({ filename: "data.db" }))
+ *   .storage(LocalFileStorage({ directory: "./uploads" }))
+ *   .collections([Posts, Users])
+ *   .build()
+ *
+ * app.serve()
+ *
+ * @example
+ * // With custom layer
+ * app.extend(MyCustomLayer).serve({ port: 8080 })
+ *
+ * @see MiraBuilder — builds MiraApp
+ * @see Mira — entry point: Mira.builder()
+ */
+export declare class MiraApp {
+    #private;
+    constructor(config: MiraAppConfig);
+    /** @internal for tests only */
+    _getConfig(): MiraAppConfig;
+    /** @internal for tests only */
+    _getExtras(): ReadonlyArray<Layer.Layer<never, never, never>>;
+    /**
+     * Add an arbitrary Effect Layer to the application's layer composition.
+     * Useful for providing custom services (e.g., custom telemetry, custom auth).
+     * Layers are merged in order of calls to `extend()`.
+     *
+     * @param layer - Any Layer<never, never, never>
+     * @returns this (for chaining)
+     *
+     * @example
+     * app.extend(Layer.succeed(MyTag, myImpl))
+     */
+    extend(layer: Layer.Layer<never, never, never>): this;
+    /**
+     * Build the full service layer without the HTTP server.
+     * Useful for testing — you can run Effects against the service layer without
+     * starting a network server.
+     *
+     * Includes: database, storage, telemetry, repository, migrator, app config,
+     * collection service (with cache), and auto-migration.
+     *
+     * @returns A Layer providing all services
+     *
+     * @example
+     * const serviceLayer = app.buildServiceLayer()
+     * const result = await Effect.runPromise(
+     *   Effect.gen(function* () { ... }).pipe(Effect.provide(serviceLayer))
+     * )
+     */
+    buildServiceLayer(): Layer.Layer<import("../index.js").FileStorage | import("./types.js").PlatformServices | import("./types.js").DatabaseServices | import("../repository/repository.js").Repository | Migrator | import("../collection-service/collection-service.js").CollectionService | import("../thumbnail/index.js").ThumbnailService | AppConfig, import("effect/ParseResult").ParseError | import("@effect/sql/SqlError").SqlError, never>;
+    /**
+     * Build the complete server layer including the HTTP router and server.
+     * Accepts an optional port override (otherwise uses the port from AppConfig).
+     *
+     * @param options.port - Optional port number override
+     * @returns A Layer ready to be launched
+     *
+     * @internal Called by serve() — most users should use serve() directly.
+     */
+    buildLayer(options?: {
+        port?: number;
+    }): Layer.Layer<HttpServer.HttpServer | import("@effect/platform/HttpPlatform").HttpPlatform | import("@effect/platform/Etag").Generator | import("../index.js").FileStorage | import("./types.js").PlatformServices | import("./types.js").DatabaseServices | import("../repository/repository.js").Repository | Migrator | import("../collection-service/collection-service.js").CollectionService | import("../thumbnail/index.js").ThumbnailService | AppConfig, import("effect/ParseResult").ParseError | import("@effect/platform/HttpServerError").ServeError | import("@effect/sql/SqlError").SqlError, never>;
+    /**
+     * Start the Mira HTTP server.
+     * Sets up all services, runs auto-migration, and listens for incoming requests.
+     * Blocks the main thread until the server is shut down.
+     *
+     * @param options.port - Optional port override (default: from AppConfig, typically 8080)
+     *
+     * @example
+     * app.serve()              // default port
+     * app.serve({ port: 8080 }) // port override
+     */
+    serve(options?: {
+        port?: number;
+    }): void;
+}
+//# sourceMappingURL=app.d.ts.map

package/dist/src/app/app.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"app.d.ts","sourceRoot":"","sources":["../../../src/app/app.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAC7C,OAAO,EAAU,KAAK,EAAE,MAAM,QAAQ,CAAA;AAEtC,OAAO,EAAE,QAAQ,EAAgB,MAAM,wBAAwB,CAAA;AAM/D,OAAO,EAAE,SAAS,EAAiB,MAAM,mBAAmB,CAAA;AAG5D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AAEjD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,qBAAa,OAAO;;gBAIN,MAAM,EAAE,aAAa;IAKjC,+BAA+B;IAC/B,UAAU,IAAI,aAAa;IAI3B,+BAA+B;IAC/B,UAAU,IAAI,aAAa,CAAC,KAAK,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC;IAI7D;;;;;;;;;;OAUG;IACH,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,CAAC,GAAG,IAAI;IAKrD;;;;;;;;;;;;;;;OAeG;IACH,iBAAiB;IAsCjB;;;;;;;;OAQG;IACH,UAAU,CAAC,OAAO,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE;IAoBtC;;;;;;;;;;OAUG;IACH,KAAK,CAAC,OAAO,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI;CAKzC"}

package/dist/src/app/app.js

@@ -0,0 +1,139 @@
+import { HttpServer } from "@effect/platform";
+import { Effect, Layer } from "effect";
+import { RepositoryLive } from "../repository/repository.js";
+import { Migrator, MigratorLive } from "../migrator/migrator.js";
+import { makeCachedCollectionServiceLayer } from "../cache/index.js";
+import { makeCollectionRouter } from "../http/router.js";
+import { ThumbnailServicePhotonLive } from "../thumbnail/index.js";
+import { ipAnnotationMiddleware } from "../http/ip-middleware.js";
+import { AppConfig, AppConfigLive } from "../config/index.js";
+import { HttpServerFactory } from "../http/server-factory.js";
+/**
+ * The assembled Mira application, ready to serve.
+ *
+ * Created by `MiraBuilder.build()`. Do not construct directly — use the
+ * `Mira.builder()` fluent API.
+ *
+ * `MiraApp` wires all layers (database, storage, collection service, HTTP server,
+ * telemetry, auto-migration) and provides `serve()` to start the server.
+ * Use `extend()` to add custom layers before serving.
+ *
+ * @example
+ * const app = Mira.builder()
+ *   .platform(NodePlatform)
+ *   .database(SqliteDatabase({ filename: "data.db" }))
+ *   .storage(LocalFileStorage({ directory: "./uploads" }))
+ *   .collections([Posts, Users])
+ *   .build()
+ *
+ * app.serve()
+ *
+ * @example
+ * // With custom layer
+ * app.extend(MyCustomLayer).serve({ port: 8080 })
+ *
+ * @see MiraBuilder — builds MiraApp
+ * @see Mira — entry point: Mira.builder()
+ */
+export class MiraApp {
+    #config;
+    #extras;
+    constructor(config) {
+        this.#config = config;
+        this.#extras = [];
+    }
+    /** @internal for tests only */
+    _getConfig() {
+        return this.#config;
+    }
+    /** @internal for tests only */
+    _getExtras() {
+        return this.#extras;
+    }
+    /**
+     * Add an arbitrary Effect Layer to the application's layer composition.
+     * Useful for providing custom services (e.g., custom telemetry, custom auth).
+     * Layers are merged in order of calls to `extend()`.
+     *
+     * @param layer - Any Layer<never, never, never>
+     * @returns this (for chaining)
+     *
+     * @example
+     * app.extend(Layer.succeed(MyTag, myImpl))
+     */
+    extend(layer) {
+        this.#extras.push(layer);
+        return this;
+    }
+    /**
+     * Build the full service layer without the HTTP server.
+     * Useful for testing — you can run Effects against the service layer without
+     * starting a network server.
+     *
+     * Includes: database, storage, telemetry, repository, migrator, app config,
+     * collection service (with cache), and auto-migration.
+     *
+     * @returns A Layer providing all services
+     *
+     * @example
+     * const serviceLayer = app.buildServiceLayer()
+     * const result = await Effect.runPromise(
+     *   Effect.gen(function* () { ... }).pipe(Effect.provide(serviceLayer))
+     * )
+     */
+    buildServiceLayer() {
+        const { platform, database, storage, collections, telemetry } = this.#config;
+        const collectionList = collections;
+        const extrasLayer = this.#extras.length > 0
+            ? this.#extras.reduce((acc, l) => Layer.merge(acc, l))
+            : Layer.empty;
+        // Foundation: database + storage + thumbnail + telemetry + extras, wired on platform
+        const foundation = Layer.mergeAll(database.layer, storage.layer, ThumbnailServicePhotonLive, telemetry, extrasLayer).pipe(Layer.provideMerge(platform.layer));
+        // Mid: Repository + Migrator + AppConfig, wired on foundation
+        const mid = Layer.mergeAll(RepositoryLive, MigratorLive, AppConfigLive).pipe(Layer.provideMerge(foundation));
+        // Auto-migrate on boot: runs during layer initialization before requests are served
+        const schemas = collectionList.map((c) => ({ name: c.name, schema: c.schema }));
+        const autoMigrateLayer = Layer.effectDiscard(Effect.gen(function* () {
+            const migrator = yield* Migrator;
+            yield* migrator.migrate(schemas);
+        }).pipe(Effect.orDie)).pipe(Layer.provide(mid));
+        // Top: CollectionService + all mid services + auto-migration side effect
+        return makeCachedCollectionServiceLayer(collectionList).pipe(Layer.provideMerge(Layer.merge(mid, autoMigrateLayer)));
+    }
+    /**
+     * Build the complete server layer including the HTTP router and server.
+     * Accepts an optional port override (otherwise uses the port from AppConfig).
+     *
+     * @param options.port - Optional port number override
+     * @returns A Layer ready to be launched
+     *
+     * @internal Called by serve() — most users should use serve() directly.
+     */
+    buildLayer(options) {
+        const { collections } = this.#config;
+        const collectionList = collections;
+        const router = makeCollectionRouter(collectionList);
+        const serviceLayer = this.buildServiceLayer();
+        const serverLayer = Layer.unwrapEffect(Effect.gen(function* () {
+            const cfg = yield* AppConfig;
+            const factory = yield* HttpServerFactory;
+            return factory.makeLayer(options?.port ?? cfg.port);
+        }));
+        return HttpServer.serve(ipAnnotationMiddleware(router)).pipe(Layer.provideMerge(serverLayer), Layer.provideMerge(serviceLayer));
+    }
+    /**
+     * Start the Mira HTTP server.
+     * Sets up all services, runs auto-migration, and listens for incoming requests.
+     * Blocks the main thread until the server is shut down.
+     *
+     * @param options.port - Optional port override (default: from AppConfig, typically 8080)
+     *
+     * @example
+     * app.serve()              // default port
+     * app.serve({ port: 8080 }) // port override
+     */
+    serve(options) {
+        this.#config.platform.runMain(Layer.launch(this.buildLayer(options)).pipe(Effect.orDie));
+    }
+}
+//# sourceMappingURL=app.js.map

package/dist/src/app/app.js.map

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

package/dist/src/app/builder.d.ts

@@ -0,0 +1,106 @@
+import type { Layer } from "effect";
+import type { AnyCollectionDef } from "@gettersethya/mira-client";
+import type { MiraPlatform, MiraDatabase, MiraStorage } from "./types.js";
+import { MiraApp } from "./app.js";
+/**
+ * Configuration object for `MiraApp`. Constructed by `MiraBuilder` after all
+ * required steps are called. Only the `telemetry` field is optional — it defaults
+ * to `ConsoleTelemetryLayer`.
+ *
+ * @see MiraBuilder — builds this config
+ */
+export interface MiraAppConfig {
+    platform: MiraPlatform;
+    database: MiraDatabase;
+    storage: MiraStorage;
+    collections: ReadonlyArray<AnyCollectionDef>;
+    telemetry: Layer.Layer<never, never, never>;
+}
+/**
+ * Phantom-type builder for constructing a `MiraApp`.
+ *
+ * Uses TypeScript's type system to enforce that all required steps are called
+ * before `build()` is allowed. The type parameter `Has` tracks which steps have
+ * been completed.
+ *
+ * Required steps (order does not matter):
+ * 1. `.platform(p)` — choose Node, Bun, etc.
+ * 2. `.database(d)` — choose SQLite, etc.
+ * 3. `.storage(s)` — choose LocalFileStorage, S3, etc.
+ * 4. `.collections(c)` — provide collection definitions
+ *
+ * Optional step: `.telemetry(l)` — custom telemetry layer
+ *
+ * @example
+ * const app = Mira.builder()
+ *   .platform(NodePlatform)
+ *   .database(SqliteDatabase({ filename: "data.db" }))
+ *   .storage(LocalFileStorage({ directory: "./uploads" }))
+ *   .collections([Posts, Users])
+ *   .build()
+ *   .serve()
+ *
+ * @see MiraApp — the assembled application
+ * @see Mira.builder — entry point
+ */
+export declare class MiraBuilder<Has extends string = never> {
+    #private;
+    constructor(config?: Partial<MiraAppConfig>);
+    /** @internal for tests only */
+    _getPartialConfig(): Partial<MiraAppConfig>;
+    /**
+     * Set the platform (runtime environment).
+     * Required step. The platform provides CryptoService, FileSystem, Path,
+     * HttpServerFactory, and AuthService implementations.
+     *
+     * @param p - A MiraPlatform preset (e.g., NodePlatform)
+     * @returns A new builder with "platform" added to the phantom type
+     */
+    platform(p: MiraPlatform): MiraBuilder<Has | "platform">;
+    /**
+     * Set the database backend.
+     * Required step. The database provides SqlClient and Dialect implementations.
+     *
+     * @param d - A MiraDatabase preset (e.g., SqliteDatabase({ filename: "data.db" }))
+     * @returns A new builder with "database" added to the phantom type
+     */
+    database(d: MiraDatabase): MiraBuilder<Has | "database">;
+    /**
+     * Set the file storage backend.
+     * Required step. Storage provides FileStorage for file upload/download operations.
+     *
+     * @param s - A MiraStorage preset (e.g., LocalFileStorage({ directory: "./uploads" }))
+     * @returns A new builder with "storage" added to the phantom type
+     */
+    storage(s: MiraStorage): MiraBuilder<Has | "storage">;
+    /**
+     * Set the collection definitions.
+     * Required step. The collections define the schema, rules, and indexes for all entities.
+     *
+     * @param c - Array of collection definitions from BaseCollection.define(), AuthCollection.define(),
+     *            or ViewCollection.define()
+     * @returns A new builder with "collections" added to the phantom type
+     */
+    collections(c: ReadonlyArray<AnyCollectionDef>): MiraBuilder<Has | "collections">;
+    /**
+     * Set a custom telemetry layer (optional).
+     * Defaults to `ConsoleTelemetryLayer` (prints JSON trace lines to stdout).
+     *
+     * @param l - A Layer providing telemetry services
+     * @returns A new builder with "telemetry" added to the phantom type
+     */
+    telemetry(l: Layer.Layer<never, never, never>): MiraBuilder<Has | "telemetry">;
+    /**
+     * Build the MiraApp from the accumulated configuration.
+     * Only compiles when all required steps (platform, database, storage, collections)
+     * have been called. If telemetry was not set, defaults to ConsoleTelemetryLayer.
+     *
+     * @param this - Constrained to MiraBuilder with all four required tags
+     * @returns A fully configured MiraApp ready to serve()
+     *
+     * @throws If build() is called before all required steps are completed
+     *         (caught at compile time by the phantom type)
+     */
+    build(this: MiraBuilder<"platform" | "database" | "storage" | "collections">): MiraApp;
+}
+//# sourceMappingURL=builder.d.ts.map

package/dist/src/app/builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"builder.d.ts","sourceRoot":"","sources":["../../../src/app/builder.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,QAAQ,CAAA;AACnC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAA;AACjE,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AACzE,OAAO,EAAE,OAAO,EAAE,MAAM,UAAU,CAAA;AAElC;;;;;;GAMG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,YAAY,CAAA;IACtB,QAAQ,EAAE,YAAY,CAAA;IACtB,OAAO,EAAE,WAAW,CAAA;IACpB,WAAW,EAAE,aAAa,CAAC,gBAAgB,CAAC,CAAA;IAC5C,SAAS,EAAE,KAAK,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,CAAC,CAAA;CAC5C;AAWD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,qBAAa,WAAW,CAAC,GAAG,SAAS,MAAM,GAAG,KAAK;;gBAGrC,MAAM,GAAE,OAAO,CAAC,aAAa,CAAM;IAI/C,+BAA+B;IAC/B,iBAAiB,IAAI,OAAO,CAAC,aAAa,CAAC;IAI3C;;;;;;;OAOG;IACH,QAAQ,CAAC,CAAC,EAAE,YAAY,GAAG,WAAW,CAAC,GAAG,GAAG,UAAU,CAAC;IAIxD;;;;;;OAMG;IACH,QAAQ,CAAC,CAAC,EAAE,YAAY,GAAG,WAAW,CAAC,GAAG,GAAG,UAAU,CAAC;IAIxD;;;;;;OAMG;IACH,OAAO,CAAC,CAAC,EAAE,WAAW,GAAG,WAAW,CAAC,GAAG,GAAG,SAAS,CAAC;IAIrD;;;;;;;OAOG;IACH,WAAW,CAAC,CAAC,EAAE,aAAa,CAAC,gBAAgB,CAAC,GAAG,WAAW,CAAC,GAAG,GAAG,aAAa,CAAC;IAIjF;;;;;;OAMG;IACH,SAAS,CAAC,CAAC,EAAE,KAAK,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,CAAC,GAAG,WAAW,CAAC,GAAG,GAAG,WAAW,CAAC;IAI9E;;;;;;;;;;OAUG;IACH,KAAK,CAAC,IAAI,EAAE,WAAW,CAAC,UAAU,GAAG,UAAU,GAAG,SAAS,GAAG,aAAa,CAAC;CAa7E"}

package/dist/src/app/builder.js

@@ -0,0 +1,122 @@
+import { ConsoleTelemetryLayer } from "../telemetry/index.js";
+import { MiraApp } from "./app.js";
+function isMiraAppConfig(config) {
+    return (config.platform !== undefined &&
+        config.database !== undefined &&
+        config.storage !== undefined &&
+        config.collections !== undefined);
+}
+/**
+ * Phantom-type builder for constructing a `MiraApp`.
+ *
+ * Uses TypeScript's type system to enforce that all required steps are called
+ * before `build()` is allowed. The type parameter `Has` tracks which steps have
+ * been completed.
+ *
+ * Required steps (order does not matter):
+ * 1. `.platform(p)` — choose Node, Bun, etc.
+ * 2. `.database(d)` — choose SQLite, etc.
+ * 3. `.storage(s)` — choose LocalFileStorage, S3, etc.
+ * 4. `.collections(c)` — provide collection definitions
+ *
+ * Optional step: `.telemetry(l)` — custom telemetry layer
+ *
+ * @example
+ * const app = Mira.builder()
+ *   .platform(NodePlatform)
+ *   .database(SqliteDatabase({ filename: "data.db" }))
+ *   .storage(LocalFileStorage({ directory: "./uploads" }))
+ *   .collections([Posts, Users])
+ *   .build()
+ *   .serve()
+ *
+ * @see MiraApp — the assembled application
+ * @see Mira.builder — entry point
+ */
+export class MiraBuilder {
+    #config;
+    constructor(config = {}) {
+        this.#config = config;
+    }
+    /** @internal for tests only */
+    _getPartialConfig() {
+        return this.#config;
+    }
+    /**
+     * Set the platform (runtime environment).
+     * Required step. The platform provides CryptoService, FileSystem, Path,
+     * HttpServerFactory, and AuthService implementations.
+     *
+     * @param p - A MiraPlatform preset (e.g., NodePlatform)
+     * @returns A new builder with "platform" added to the phantom type
+     */
+    platform(p) {
+        return new MiraBuilder({ ...this.#config, platform: p });
+    }
+    /**
+     * Set the database backend.
+     * Required step. The database provides SqlClient and Dialect implementations.
+     *
+     * @param d - A MiraDatabase preset (e.g., SqliteDatabase({ filename: "data.db" }))
+     * @returns A new builder with "database" added to the phantom type
+     */
+    database(d) {
+        return new MiraBuilder({ ...this.#config, database: d });
+    }
+    /**
+     * Set the file storage backend.
+     * Required step. Storage provides FileStorage for file upload/download operations.
+     *
+     * @param s - A MiraStorage preset (e.g., LocalFileStorage({ directory: "./uploads" }))
+     * @returns A new builder with "storage" added to the phantom type
+     */
+    storage(s) {
+        return new MiraBuilder({ ...this.#config, storage: s });
+    }
+    /**
+     * Set the collection definitions.
+     * Required step. The collections define the schema, rules, and indexes for all entities.
+     *
+     * @param c - Array of collection definitions from BaseCollection.define(), AuthCollection.define(),
+     *            or ViewCollection.define()
+     * @returns A new builder with "collections" added to the phantom type
+     */
+    collections(c) {
+        return new MiraBuilder({ ...this.#config, collections: c });
+    }
+    /**
+     * Set a custom telemetry layer (optional).
+     * Defaults to `ConsoleTelemetryLayer` (prints JSON trace lines to stdout).
+     *
+     * @param l - A Layer providing telemetry services
+     * @returns A new builder with "telemetry" added to the phantom type
+     */
+    telemetry(l) {
+        return new MiraBuilder({ ...this.#config, telemetry: l });
+    }
+    /**
+     * Build the MiraApp from the accumulated configuration.
+     * Only compiles when all required steps (platform, database, storage, collections)
+     * have been called. If telemetry was not set, defaults to ConsoleTelemetryLayer.
+     *
+     * @param this - Constrained to MiraBuilder with all four required tags
+     * @returns A fully configured MiraApp ready to serve()
+     *
+     * @throws If build() is called before all required steps are completed
+     *         (caught at compile time by the phantom type)
+     */
+    build() {
+        const config = this._getPartialConfig();
+        if (!isMiraAppConfig(config)) {
+            throw new Error("build() called on incomplete builder");
+        }
+        return new MiraApp({
+            platform: config.platform,
+            database: config.database,
+            storage: config.storage,
+            collections: config.collections,
+            telemetry: config.telemetry ?? ConsoleTelemetryLayer
+        });
+    }
+}
+//# sourceMappingURL=builder.js.map

package/dist/src/app/builder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"builder.js","sourceRoot":"","sources":["../../../src/app/builder.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAA;AAI5D,OAAO,EAAE,OAAO,EAAE,MAAM,UAAU,CAAA;AAiBlC,SAAS,eAAe,CAAC,MAA8B;IACrD,OAAO,CACL,MAAM,CAAC,QAAQ,KAAK,SAAS;QAC7B,MAAM,CAAC,QAAQ,KAAK,SAAS;QAC7B,MAAM,CAAC,OAAO,KAAK,SAAS;QAC5B,MAAM,CAAC,WAAW,KAAK,SAAS,CACjC,CAAA;AACH,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,OAAO,WAAW;IACb,OAAO,CAAwB;IAExC,YAAY,SAAiC,EAAE;QAC7C,IAAI,CAAC,OAAO,GAAG,MAAM,CAAA;IACvB,CAAC;IAED,+BAA+B;IAC/B,iBAAiB;QACf,OAAO,IAAI,CAAC,OAAO,CAAA;IACrB,CAAC;IAED;;;;;;;OAOG;IACH,QAAQ,CAAC,CAAe;QACtB,OAAO,IAAI,WAAW,CAAC,EAAE,GAAG,IAAI,CAAC,OAAO,EAAE,QAAQ,EAAE,CAAC,EAAE,CAAC,CAAA;IAC1D,CAAC;IAED;;;;;;OAMG;IACH,QAAQ,CAAC,CAAe;QACtB,OAAO,IAAI,WAAW,CAAC,EAAE,GAAG,IAAI,CAAC,OAAO,EAAE,QAAQ,EAAE,CAAC,EAAE,CAAC,CAAA;IAC1D,CAAC;IAED;;;;;;OAMG;IACH,OAAO,CAAC,CAAc;QACpB,OAAO,IAAI,WAAW,CAAC,EAAE,GAAG,IAAI,CAAC,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,CAAC,CAAA;IACzD,CAAC;IAED;;;;;;;OAOG;IACH,WAAW,CAAC,CAAkC;QAC5C,OAAO,IAAI,WAAW,CAAC,EAAE,GAAG,IAAI,CAAC,OAAO,EAAE,WAAW,EAAE,CAAC,EAAE,CAAC,CAAA;IAC7D,CAAC;IAED;;;;;;OAMG;IACH,SAAS,CAAC,CAAmC;QAC3C,OAAO,IAAI,WAAW,CAAC,EAAE,GAAG,IAAI,CAAC,OAAO,EAAE,SAAS,EAAE,CAAC,EAAE,CAAC,CAAA;IAC3D,CAAC;IAED;;;;;;;;;;OAUG;IACH,KAAK;QACH,MAAM,MAAM,GAAG,IAAI,CAAC,iBAAiB,EAAE,CAAA;QACvC,IAAI,CAAC,eAAe,CAAC,MAAM,CAAC,EAAE,CAAC;YAC7B,MAAM,IAAI,KAAK,CAAC,sCAAsC,CAAC,CAAA;QACzD,CAAC;QACD,OAAO,IAAI,OAAO,CAAC;YACjB,QAAQ,EAAE,MAAM,CAAC,QAAQ;YACzB,QAAQ,EAAE,MAAM,CAAC,QAAQ;YACzB,OAAO,EAAE,MAAM,CAAC,OAAO;YACvB,WAAW,EAAE,MAAM,CAAC,WAAW;YAC/B,SAAS,EAAE,MAAM,CAAC,SAAS,IAAI,qBAAqB;SACrD,CAAC,CAAA;IACJ,CAAC;CACF"}

package/dist/src/app/index.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Entry point for the Mira server library.
+ *
+ * Usage:
+ * ```ts
+ * import { Mira, NodePlatform, SqliteDatabase, LocalFileStorage } from "@gettersethya/mira"
+ *
+ * const app = Mira.builder()
+ *   .platform(NodePlatform)
+ *   .database(SqliteDatabase({ filename: "data.db" }))
+ *   .storage(LocalFileStorage({ directory: "./uploads" }))
+ *   .collections([Posts, Users])
+ *   .build()
+ *   .serve()
+ * ```
+ *
+ * @example
+ * // Server-only: all client exports are re-exported from @gettersethya/mira too
+ * import { BaseCollection, Field } from "@gettersethya/mira"
+ *
+ * @see MiraBuilder — the phantom-type fluent builder
+ * @see MiraApp — the assembled server
+ */
+import { MiraBuilder } from "./builder.js";
+export declare const Mira: {
+    builder: () => MiraBuilder<never>;
+};
+export type { MiraPlatform, MiraDatabase, MiraStorage } from "./types.js";
+export type { MiraApp } from "./app.js";
+export { MiraBuilder } from "./builder.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/src/app/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/app/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAA;AAE1C,eAAO,MAAM,IAAI;;CAEhB,CAAA;AAED,YAAY,EAAE,YAAY,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AACzE,YAAY,EAAE,OAAO,EAAE,MAAM,UAAU,CAAA;AACvC,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAA"}

package/dist/src/app/index.js

@@ -0,0 +1,29 @@
+/**
+ * Entry point for the Mira server library.
+ *
+ * Usage:
+ * ```ts
+ * import { Mira, NodePlatform, SqliteDatabase, LocalFileStorage } from "@gettersethya/mira"
+ *
+ * const app = Mira.builder()
+ *   .platform(NodePlatform)
+ *   .database(SqliteDatabase({ filename: "data.db" }))
+ *   .storage(LocalFileStorage({ directory: "./uploads" }))
+ *   .collections([Posts, Users])
+ *   .build()
+ *   .serve()
+ * ```
+ *
+ * @example
+ * // Server-only: all client exports are re-exported from @gettersethya/mira too
+ * import { BaseCollection, Field } from "@gettersethya/mira"
+ *
+ * @see MiraBuilder — the phantom-type fluent builder
+ * @see MiraApp — the assembled server
+ */
+import { MiraBuilder } from "./builder.js";
+export const Mira = {
+    builder: () => new MiraBuilder(),
+};
+export { MiraBuilder } from "./builder.js";
+//# sourceMappingURL=index.js.map

package/dist/src/app/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/app/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAA;AAE1C,MAAM,CAAC,MAAM,IAAI,GAAG;IAClB,OAAO,EAAE,GAAG,EAAE,CAAC,IAAI,WAAW,EAAE;CACjC,CAAA;AAID,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAA"}

package/dist/src/app/types.d.ts

@@ -0,0 +1,55 @@
+import type { FileSystem, Path } from "@effect/platform";
+import type { Effect, Layer } from "effect";
+import type { SqlClient } from "@effect/sql";
+import type { AuthService } from "../http/auth.js";
+import type { HttpServerFactory } from "../http/server-factory.js";
+import type { CryptoService } from "../crypto/crypto.js";
+import type { Dialect } from "../migrator/dialect.js";
+import type { FileStorage } from "../storage/storage.js";
+/**
+ * Services that a platform preset must provide.
+ * Union type including CryptoService, FileSystem, Path, HttpServerFactory, and AuthService.
+ *
+ * @see MiraPlatform — requires a Layer providing these services
+ */
+export type PlatformServices = CryptoService | FileSystem.FileSystem | Path.Path | HttpServerFactory | AuthService;
+/**
+ * Services that a database preset must provide.
+ * Union type including SqlClient and Dialect.
+ *
+ * @see MiraDatabase — requires a Layer providing these services
+ */
+export type DatabaseServices = SqlClient.SqlClient | Dialect;
+/**
+ * Interface for a platform preset (e.g., Node, Bun).
+ * Must provide a Layer with all PlatformServices and a `runMain` function
+ * that runs an Effect to completion.
+ *
+ * @see NodePlatform — Node.js implementation
+ * @see MiraBuilder.platform — where MiraPlatform is used
+ */
+export interface MiraPlatform {
+    layer: Layer.Layer<PlatformServices>;
+    runMain: (effect: Effect.Effect<never, never, never>) => void;
+}
+/**
+ * Interface for a database preset (e.g., SQLite).
+ * Must provide a Layer with all DatabaseServices.
+ *
+ * @see SqliteDatabase — SQLite implementation
+ * @see MiraBuilder.database — where MiraDatabase is used
+ */
+export interface MiraDatabase {
+    layer: Layer.Layer<DatabaseServices>;
+}
+/**
+ * Interface for a storage preset (e.g., local disk, S3).
+ * Must provide a Layer with FileStorage, requiring FileSystem and Path.
+ *
+ * @see LocalFileStorage — local disk implementation
+ * @see MiraBuilder.storage — where MiraStorage is used
+ */
+export interface MiraStorage {
+    layer: Layer.Layer<FileStorage, never, FileSystem.FileSystem | Path.Path>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/src/app/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/app/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAA;AACxD,OAAO,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,QAAQ,CAAA;AAC3C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AAC5C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAA;AACjD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAA;AACjE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AACvD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAA;AACpD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAA;AAEvD;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,GACxB,aAAa,GACb,UAAU,CAAC,UAAU,GACrB,IAAI,CAAC,IAAI,GACT,iBAAiB,GACjB,WAAW,CAAA;AAEf;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,GAAG,SAAS,CAAC,SAAS,GAAG,OAAO,CAAA;AAE5D;;;;;;;GAOG;AACH,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC,gBAAgB,CAAC,CAAA;IACpC,OAAO,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,IAAI,CAAA;CAC9D;AAED;;;;;;GAMG;AACH,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC,gBAAgB,CAAC,CAAA;CACrC;AAED;;;;;;GAMG;AACH,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC,WAAW,EAAE,KAAK,EAAE,UAAU,CAAC,UAAU,GAAG,IAAI,CAAC,IAAI,CAAC,CAAA;CAC1E"}

package/dist/src/app/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/src/app/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/app/types.ts"],"names":[],"mappings":""}