@gettersethya/mira 0.1.0-alpha.10

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/README.md

@@ -0,0 +1,103 @@
+# @gettersethya/mira
+
+> **Early pre-alpha.** Breaking changes may occur without notice.
+
+Self-hosted backend in TypeScript using [Effect](https://effect.website). Define collections, get a full REST API with auth, file storage, access rules, and schema migrations — all with zero config.
+
+## Installation
+
+```bash
+npm install @gettersethya/mira @gettersethya/mira-collection effect
+# or
+pnpm add @gettersethya/mira @gettersethya/mira-collection effect
+```
+
+## Quick start
+
+```typescript
+import { LocalFileStorage, Mira, NodePlatform, SqliteDatabase } from "@gettersethya/mira"
+import { Posts, Users } from "./collections.js"
+
+const app = Mira.builder()
+  .platform(NodePlatform)
+  .database(SqliteDatabase({ filename: "mira.db" }))
+  .storage(LocalFileStorage({ directory: "./uploads" }))
+  .collections([Users, Posts])
+  .build()
+
+app.serve({ port: 3000 })
+```
+
+The builder uses phantom types to enforce step ordering — TypeScript will not let you call `.build()` until all four steps are complete.
+
+On first boot, Mira auto-generates a `jwt_secret`, runs schema migrations, and creates SQL views for view collections. Everything is persisted in the database.
+
+## Builder steps
+
+| Step | Required | Description |
+|---|---|---|
+| `.platform(p)` | Yes | Runtime environment (Node.js, etc.) |
+| `.database(d)` | Yes | Database backend |
+| `.storage(s)` | Yes | File storage backend |
+| `.collections(c)` | Yes | Collection definitions |
+| `.telemetry(layer)` | No | Custom Effect telemetry layer |
+| `.extend(layer)` | No | Inject additional layers before serving |
+
+## Platforms
+
+```typescript
+import { NodePlatform } from "@gettersethya/mira"
+
+// Provides: CryptoService, FileSystem, HttpServerFactory, AuthService
+```
+
+## Databases
+
+```typescript
+import { SqliteDatabase } from "@gettersethya/mira"
+
+SqliteDatabase({ filename: "mira.db" })
+SqliteDatabase({ filename: ":memory:" })  // in-memory for tests
+```
+
+## Storage
+
+```typescript
+import { LocalFileStorage } from "@gettersethya/mira"
+
+LocalFileStorage({ directory: "./uploads" })
+```
+
+## Auto-generated endpoints
+
+Each collection gets a full set of REST endpoints:
+
+| Method | Path | Description |
+|---|---|---|
+| `GET` | `/api/:collection` | List (filter, sort, cursor, expand, select) |
+| `GET` | `/api/:collection/:id` | Get one |
+| `POST` | `/api/:collection` | Create |
+| `PATCH` | `/api/:collection/:id` | Update |
+| `DELETE` | `/api/:collection/:id` | Delete |
+| `POST` | `/api/:collection/authWithPassword` | Login (auth collections only) |
+| `POST` | `/api/auth/logout` | Logout |
+| `POST` | `/api/files/token` | Request protected file token |
+| `GET` | `/api/files/:collection/:id/:filename` | Serve file |
+
+## Testing with the service layer
+
+Use `.buildServiceLayer()` to get an Effect `Layer` for all services without starting an HTTP server:
+
+```typescript
+import { Effect, Layer } from "effect"
+
+const serviceLayer = app.buildServiceLayer()
+
+const test = Effect.gen(function* () {
+  // inject and use services directly
+}).pipe(Effect.provide(serviceLayer))
+```
+
+## More
+
+See the [Mira root README](https://github.com/gettersethya/mira) for collection definitions, field types, rules, filter DSL, and client usage.

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

@@ -0,0 +1,100 @@
+import { HttpServer } from "@effect/platform";
+import { Layer } from "effect";
+import { Migrator } from "../migrator/migrator.js";
+import { AppConfig } from "../config/index.js";
+import type { Repository } from "../repository/index.js";
+import type { CollectionService } from "../collection-service/collection-service.js";
+import type { MiraAppConfig } from "./builder.js";
+import type { MiraPlugin } from "./plugin.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 plugins 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 plugin
+ * app.extend(MiraDashboard).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<MiraPlugin>;
+    /**
+     * Add a plugin to the application. Plugins can register lifecycle hooks,
+     * record-lifecycle hooks, custom routes, service layers, and additional
+     * collection definitions.
+     *
+     * @param plugin - A MiraPlugin (use `fromLayer()` to wrap a plain Layer)
+     * @returns this (for chaining)
+     *
+     * @example
+     * app.extend(MiraDashboard).serve()
+     */
+    extend(plugin: MiraPlugin): 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 + hooks), 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<Migrator | import("../index.js").FileStorage | import("./types.js").PlatformServices | import("./types.js").DatabaseServices | Repository | CollectionService | import("../thumbnail/index.js").ThumbnailService | AppConfig, import("effect/ParseResult").ParseError | import("@effect/sql/SqlError").SqlError, CollectionService>;
+    /**
+     * 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<Migrator | HttpServer.HttpServer | import("@effect/platform/HttpPlatform").HttpPlatform | import("@effect/platform/Etag").Generator | import("../index.js").FileStorage | import("./types.js").PlatformServices | import("./types.js").DatabaseServices | Repository | CollectionService | import("../thumbnail/index.js").ThumbnailService | AppConfig, import("effect/ParseResult").ParseError | import("@effect/sql/SqlError").SqlError | import("@effect/platform/HttpServerError").ServeError, CollectionService>;
+    /**
+     * Start the Mira HTTP server.
+     * Sets up all services, runs auto-migration, runs plugin lifecycle hooks,
+     * 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,EAA0B,UAAU,EAAQ,MAAM,kBAAkB,CAAA;AAE3E,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,UAAU,EAAE,MAAM,uBAAuB,CAAA;AACvD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,4CAA4C,CAAA;AAEnF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AACjD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAK7C;;;;;;;;;;;;;;;;;;;;;;;;;;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,UAAU,CAAC;IAIvC;;;;;;;;;;OAUG;IACH,MAAM,CAAC,MAAM,EAAE,UAAU,GAAG,IAAI;IAgBhC;;;;;;;;;;;;;;;OAeG;IACH,iBAAiB;IAgDjB;;;;;;;;OAQG;IACH,UAAU,CAAC,OAAO,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE;IAgCtC;;;;;;;;;;;OAWG;IACH,KAAK,CAAC,OAAO,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI;CAczC"}

package/dist/src/app/app.js

@@ -0,0 +1,176 @@
+import { HttpRouter, 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";
+import { makeHookServiceLayer } from "../hooks/hook-service.js";
+import { makeHookCollectionServiceLayer } from "../hooks/hook-collection.js";
+import { HookService } from "../hooks/hook-service.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 plugins 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 plugin
+ * app.extend(MiraDashboard).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 a plugin to the application. Plugins can register lifecycle hooks,
+     * record-lifecycle hooks, custom routes, service layers, and additional
+     * collection definitions.
+     *
+     * @param plugin - A MiraPlugin (use `fromLayer()` to wrap a plain Layer)
+     * @returns this (for chaining)
+     *
+     * @example
+     * app.extend(MiraDashboard).serve()
+     */
+    extend(plugin) {
+        this.#extras.push(plugin);
+        return this;
+    }
+    #getAllCollections() {
+        return [
+            ...this.#config.collections,
+            ...this.#extras.flatMap((p) => p.collections ?? [])
+        ];
+    }
+    #getAllPlugins() {
+        return this.#extras;
+    }
+    /**
+     * 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 + hooks), 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, telemetry } = this.#config;
+        const allCollections = this.#getAllCollections();
+        const allPlugins = this.#getAllPlugins();
+        const pluginLayers = allPlugins.filter((p) => p.layer !== undefined).map((p) => p.layer);
+        const extrasLayer = pluginLayers.length > 0 ? pluginLayers.reduce((acc, l) => Layer.merge(acc, l)) : Layer.empty;
+        // Foundation: database + storage + thumbnail + telemetry, wired on platform
+        const foundation = Layer.mergeAll(database.layer, storage.layer, ThumbnailServicePhotonLive, telemetry).pipe(Layer.provideMerge(platform.layer));
+        // Mid: Repository + Migrator + AppConfig, wired on foundation
+        const mid = Layer.mergeAll(RepositoryLive, MigratorLive, AppConfigLive).pipe(Layer.provideMerge(foundation));
+        // Extras: plugin layers run after mid so they can depend on AppConfig + platform services
+        const extrasProvided = extrasLayer.pipe(Layer.provide(mid));
+        const fullMid = Layer.merge(mid, extrasProvided);
+        // Auto-migrate on boot: runs during layer initialization before requests are served
+        const schemas = allCollections.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(fullMid));
+        // Core collection service (cached)
+        const cachedCollectionLayer = makeCachedCollectionServiceLayer(allCollections);
+        // Hook service layer (collects all plugin hooks)
+        const hookServiceLayer = makeHookServiceLayer(allPlugins);
+        // Hook collection service decorator: wraps cached collection service with hooks
+        const hookCollectionLayer = makeHookCollectionServiceLayer().pipe(Layer.provide(Layer.mergeAll(cachedCollectionLayer, hookServiceLayer)));
+        // Top: hook-wrapped collection service + all mid services + auto-migration side effect
+        return hookCollectionLayer.pipe(Layer.provideMerge(Layer.merge(fullMid, 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 allCollections = this.#getAllCollections();
+        const collectionRouter = makeCollectionRouter(allCollections);
+        // Plugin routes
+        let pluginRouter = HttpRouter.empty;
+        for (const plugin of this.#extras) {
+            if (plugin.routes !== undefined) {
+                pluginRouter = HttpRouter.concat(pluginRouter, plugin.routes);
+            }
+        }
+        const router = HttpRouter.concat(collectionRouter, pluginRouter);
+        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, runs plugin lifecycle hooks,
+     * 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) {
+        const allPlugins = this.#getAllPlugins();
+        const hookServiceLayer = makeHookServiceLayer(allPlugins);
+        const fullLayer = this.buildLayer(options);
+        this.#config.platform.runMain(Effect.gen(this, function* () {
+            const hookService = yield* HookService.pipe(Effect.provide(hookServiceLayer));
+            const bootstrapLayer = Layer.effectDiscard(hookService.runBootstrap());
+            yield* Layer.launch(bootstrapLayer.pipe(Layer.provideMerge(fullLayer)));
+            yield* hookService.runServe();
+        }));
+    }
+}
+//# 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"}