@maykonpaulo/maestro-server 0.1.0-next.1

package/README.md

@@ -0,0 +1,115 @@
+# @maykonpaulo/maestro-server
+
+The **turnkey HTTP server** for [`@maykonpaulo/maestro-core`](https://www.npmjs.com/package/@maykonpaulo/maestro-core), per [ADR 0008 — Camada Turnkey](../../docs/adr/0008-turnkey-server-and-admin-ui.md).
+
+The core is deliberately server-free and framework-agnostic: it exposes `createMaestroHttpHandlers` (handlers you mount on *your* Express/Fastify/Lambda), never an actual server. This sibling package is the batteries-included layer that boots a real HTTP server, and — combined with a live datasource provider — turns **any database into a complete, governed admin over every collection, without writing a line of per-entity code**.
+
+It adds only what a server needs and the core must not carry: JSON body parsing, CORS, route wiring and a `listen()`/`close()` lifecycle. All domain behaviour (RBAC, audit, governance, CRUD) still comes from the engine.
+
+## Installation
+
+```bash
+npm install @maykonpaulo/maestro-server @maykonpaulo/maestro-core
+```
+
+`@maykonpaulo/maestro-core` is a peer dependency. `express` is a direct dependency of this package.
+
+## Point at a database, manipulate everything (introspection mode)
+
+The fastest path: hand it a live provider (e.g. [`@maykonpaulo/maestro-provider-mongodb`](../provider-mongodb)) and get a full admin over every discovered collection — no declarations required.
+
+```ts
+import { createMongoProvider } from '@maykonpaulo/maestro-provider-mongodb';
+import { createMaestroServer, createIntrospectedEngine } from '@maykonpaulo/maestro-server';
+
+const provider = createMongoProvider({ uri: process.env.MONGO_URL!, database: 'app' });
+
+// Introspects the live DB and builds an engine over every collection, with write access enabled.
+const engine = await createIntrospectedEngine({ provider, access: 'full' });
+
+const server = createMaestroServer({ engine });
+await server.listen(3000);
+// → REST admin for every collection at http://localhost:3000/entities/:collection
+```
+
+`access: 'readonly'` enables only `list`/`detail`/`export` — a safe way to browse a production database without any risk of mutating it. `access: 'full'` (default) enables the complete CRUD surface.
+
+> Entities discovered by introspection are read-only under the core's `createMaestroFromIntrospection`; `createIntrospectedEngine` is the piece that enables write capabilities according to `access`, so "manipulate everything" works out of the box.
+
+## Curated mode (declarations)
+
+When you want nice labels, fine-grained RBAC and governance on chosen entities, build the engine yourself with `createMaestro` and just serve it:
+
+```ts
+import { createMaestro } from '@maykonpaulo/maestro-core';
+import { createMaestroServer } from '@maykonpaulo/maestro-server';
+
+const engine = createMaestro({ datasources: { main: provider }, declarations, policies, audit });
+const server = createMaestroServer({ engine, actorResolver });
+await server.listen(3000);
+```
+
+Both modes can be combined: pass an `overrides` (curated) config to `createIntrospectedEngine` and the core `HybridLoader` merges it over the introspected schema.
+
+## Authentication is yours (the `actorResolver` hook)
+
+Authentication stays the consumer's responsibility. `createMaestroServer` takes an `actorResolver` that derives the acting `Actor` from each request (a JWT, a cookie, a session):
+
+```ts
+const server = createMaestroServer({
+  engine,
+  actorResolver: async (req) => {
+    const user = await verifyJwt(req.headers['authorization']);
+    return { actor: { id: user.id, type: 'user', roles: user.roles } };
+  },
+});
+```
+
+When omitted, a **development-only** `devActorResolver` grants every request a single admin actor. Never use it in production.
+
+## API
+
+### `createMaestroServer(options): MaestroServer`
+
+| Option | Description |
+|---|---|
+| `engine` | The `MaestroEngine` to serve (from `createMaestro` or `createIntrospectedEngine`). |
+| `actorResolver?` | Resolves the `Actor` per request. Defaults to `devActorResolver` (dev only). |
+| `cors?` | `true`/omitted → permissive defaults; an object → configured (`origin`, `credentials`, `allowedHeaders`); `false` → no CORS middleware. |
+| `basePath?` | Path prefix for every route (e.g. `/api/admin`). |
+| `app?` | Bring your own Express app (to add auth middleware/other routes). When given, JSON/CORS are not auto-applied. |
+
+Returns `{ app, handlers, listen(port, host?) }`. `listen` resolves with the Node `http.Server` once bound.
+
+### `createIntrospectedEngine(options): Promise<MaestroEngine>`
+
+| Option | Description |
+|---|---|
+| `provider` | A provider implementing both `IntrospectionProvider` and `DatasourceProvider`. |
+| `access?` | `'full'` (default) enables all capabilities; `'readonly'` enables list/detail/export only. |
+| `datasourceId?` | Datasource id the entities bind to. Defaults to `main`. |
+| `overrides?` | Optional curated overlay merged via the core `HybridLoader`. |
+| `policies?` | RBAC policy. Defaults to an `admin` role with `['*']`. |
+| `operations?`, `audit?`, `logger?` | Forwarded to the engine. |
+
+## Routes
+
+```
+GET    /health
+GET    /metadata
+GET    /metadata/:entity
+GET    /entities/:entity            (list — filter/sort/paginate/search via query string)
+POST   /entities/:entity            (create)
+GET    /entities/:entity/:id        (detail)
+PATCH  /entities/:entity/:id        (update)
+DELETE /entities/:entity/:id        (hard delete)
+POST   /entities/:entity/:id/clone
+POST   /entities/:entity/:id/soft-delete
+POST   /entities/:entity/:id/restore
+GET    /entities/:entity/export     (?format=csv|json)
+POST   /operations/:operationId
+```
+
+## What this package is not
+
+It bundles **no database driver** — it depends on a `DatasourceProvider` you instantiate (the driver comes with the provider package). It does **not** handle authentication or identity — that is the `actorResolver`'s job. Those boundaries are intentional and preserve the core's purity (ADR 0008).

package/dist/index.d.ts

@@ -0,0 +1,101 @@
+import { Server } from 'node:http';
+import { Express } from 'express';
+import { MaestroEngine, MaestroActorResolver, MaestroHttpHandlers, IntrospectionProvider, DatasourceProvider, LoadedConfig, RbacPolicy, OperationDef, AuditRepository, Logger } from '@maykonpaulo/maestro-core';
+
+interface CorsOptions {
+    /** Allowed origin. Defaults to `*`. Set to a concrete origin when using credentials. */
+    origin?: string;
+    /** Emit `Access-Control-Allow-Credentials: true`. Defaults to false. */
+    credentials?: boolean;
+    /** Extra request headers to allow, appended to the defaults. */
+    allowedHeaders?: string[];
+}
+/**
+ * A dependency-free CORS middleware. Kept tiny on purpose — the turnkey server should not pull an extra
+ * package for a handful of headers, and a consumer with stricter needs can disable this and mount their own.
+ */
+declare function applyCors(app: Express, options?: CorsOptions): void;
+
+interface CreateMaestroServerOptions {
+    /** The engine to serve. Build it from declarations (`createMaestro`) or from a live database (`createIntrospectedEngine`). */
+    engine: MaestroEngine;
+    /**
+     * Resolves the acting `Actor` for each request (authentication is the consumer's responsibility).
+     * Defaults to {@link devActorResolver} — a single admin actor, suitable only for local development.
+     */
+    actorResolver?: MaestroActorResolver;
+    /** CORS handling. `true`/omitted → permissive defaults; an object → configured; `false` → no CORS middleware. */
+    cors?: boolean | CorsOptions;
+    /** Path prefix for every route (e.g. `/api/admin`). Defaults to none. */
+    basePath?: string;
+    /**
+     * Bring your own Express app to mount the routes on (to add auth middleware, logging, other routes, etc.).
+     * When omitted, a fresh app is created with a JSON body parser and CORS.
+     */
+    app?: Express;
+}
+interface MaestroServer {
+    /** The Express app with all Maestro routes mounted. Mount extra routes/middleware before calling `listen`. */
+    app: Express;
+    /** The underlying framework-agnostic handlers, in case you want to mount a subset yourself. */
+    handlers: MaestroHttpHandlers;
+    /** Starts listening and resolves with the Node `http.Server` once bound. */
+    listen(port: number, host?: string): Promise<Server>;
+}
+/**
+ * Mounts the Maestro HTTP handlers on a real Express server — the turnkey layer the core deliberately
+ * omits (ADR 0008). It adds only what a server needs and the core must not carry: JSON body parsing,
+ * CORS, route wiring and a `listen()` lifecycle. All domain behaviour still comes from the engine.
+ */
+declare function createMaestroServer(options: CreateMaestroServerOptions): MaestroServer;
+
+/** Access level applied to entities discovered by introspection. */
+type IntrospectedAccess = 'full' | 'readonly';
+interface CreateIntrospectedEngineOptions {
+    /**
+     * A live provider that can both describe the database (`introspect`) and operate it (`list/create/...`).
+     * The MongoDB, SQL, and other official providers implement both interfaces on a single instance.
+     */
+    provider: IntrospectionProvider & DatasourceProvider;
+    /** Datasource id the discovered entities are bound to. Defaults to `main`. */
+    datasourceId?: string;
+    /**
+     * `full` (default) enables every capability on discovered entities, turning the engine into a complete
+     * database manipulator. `readonly` enables only list/detail/export — a safe way to browse a database
+     * without any risk of mutating it.
+     */
+    access?: IntrospectedAccess;
+    /**
+     * Optional curated overlay (labels, extra fields, relations, RBAC) merged over the introspected schema
+     * via the core `HybridLoader`. Entities you curate here keep their own explicit `capabilities`.
+     */
+    overrides?: LoadedConfig;
+    /**
+     * RBAC policy for the engine. When omitted, a default `admin` role with `['*']` is used — appropriate
+     * for a single platform operator and meant to be replaced with a real policy in multi-role deployments.
+     */
+    policies?: RbacPolicy;
+    operations?: OperationDef[];
+    audit?: AuditRepository;
+    logger?: Logger;
+}
+/**
+ * Builds a `MaestroEngine` directly from a live database, with no per-entity declaration required
+ * (ADR 0008, DA-17). It introspects the provider, turns every discovered collection/table into a
+ * manipulable entity, and — unlike `createMaestroFromIntrospection`, whose entities are read-only by
+ * default — enables write capabilities according to `access`, so "point at the database and manipulate
+ * everything" works out of the box.
+ *
+ * Uses only public core exports (`introspect` → `mergeIntrospectionWithOverrides` → `createMaestro`).
+ */
+declare function createIntrospectedEngine(options: CreateIntrospectedEngineOptions): Promise<MaestroEngine>;
+
+/**
+ * The default resolver used when `createMaestroServer` is called without one. It grants every request a
+ * single admin actor — convenient for local development and demos, and **never** appropriate for
+ * production. In production the consumer supplies its own resolver (deriving the actor from a JWT, cookie
+ * or session), keeping authentication the consumer's responsibility (ADR 0008, DA-18).
+ */
+declare const devActorResolver: MaestroActorResolver;
+
+export { type CorsOptions, type CreateIntrospectedEngineOptions, type CreateMaestroServerOptions, type IntrospectedAccess, type MaestroServer, applyCors, createIntrospectedEngine, createMaestroServer, devActorResolver };

package/dist/index.js

@@ -0,0 +1,188 @@
+// src/createMaestroServer.ts
+import { createServer } from "http";
+import express from "express";
+import { createMaestroHttpHandlers } from "@maykonpaulo/maestro-core";
+
+// src/expressAdapter.ts
+function toMaestroRequest(req) {
+  return {
+    params: req.params,
+    query: req.query,
+    body: req.body,
+    headers: req.headers,
+    method: req.method,
+    path: req.path
+  };
+}
+function adapt(handler) {
+  return async (req, res) => {
+    const response = await handler(toMaestroRequest(req));
+    if (response.headers) {
+      for (const [key, value] of Object.entries(response.headers)) {
+        res.setHeader(key, value);
+      }
+    }
+    res.status(response.status);
+    if (response.body === null || response.body === void 0) {
+      res.end();
+    } else if (typeof response.body === "string") {
+      res.send(response.body);
+    } else {
+      res.json(response.body);
+    }
+  };
+}
+
+// src/cors.ts
+var DEFAULT_HEADERS = ["Content-Type", "Authorization", "X-Role"];
+var ALLOWED_METHODS = "GET,POST,PATCH,DELETE,OPTIONS";
+function applyCors(app, options = {}) {
+  const headers = [...DEFAULT_HEADERS, ...options.allowedHeaders ?? []].join(", ");
+  app.use((req, res, next) => {
+    res.setHeader("Access-Control-Allow-Origin", options.origin ?? "*");
+    res.setHeader("Access-Control-Allow-Methods", ALLOWED_METHODS);
+    res.setHeader("Access-Control-Allow-Headers", headers);
+    if (options.credentials) res.setHeader("Access-Control-Allow-Credentials", "true");
+    if (req.method === "OPTIONS") {
+      res.status(204).end();
+      return;
+    }
+    next();
+  });
+}
+
+// src/devActorResolver.ts
+var devActorResolver = async () => ({
+  actor: {
+    id: "dev-admin",
+    type: "user",
+    name: "Development Admin",
+    roles: ["admin"]
+  }
+});
+
+// src/createMaestroServer.ts
+var ROUTES = {
+  health: "/health",
+  metadata: "/metadata",
+  entityMetadata: "/metadata/:entity",
+  operation: "/operations/:operationId",
+  export: "/entities/:entity/export",
+  list: "/entities/:entity",
+  create: "/entities/:entity",
+  findById: "/entities/:entity/:id",
+  update: "/entities/:entity/:id",
+  clone: "/entities/:entity/:id/clone",
+  softDelete: "/entities/:entity/:id/soft-delete",
+  restore: "/entities/:entity/:id/restore",
+  hardDelete: "/entities/:entity/:id"
+};
+function createMaestroServer(options) {
+  const actorResolver = options.actorResolver ?? devActorResolver;
+  const handlers = createMaestroHttpHandlers(options.engine, { actorResolver });
+  const app = options.app ?? express();
+  if (!options.app) {
+    if (options.cors !== false) {
+      applyCors(app, typeof options.cors === "object" ? options.cors : {});
+    }
+    app.use(express.json());
+  }
+  const base = options.basePath ?? "";
+  const at = (path) => `${base}${path}`;
+  app.get(at(ROUTES.health), adapt(handlers.health));
+  app.get(at(ROUTES.metadata), adapt(handlers.getMetadata));
+  app.get(at(ROUTES.entityMetadata), adapt(handlers.getEntityMetadata));
+  app.post(at(ROUTES.operation), adapt(handlers.executeOperation));
+  app.get(at(ROUTES.export), adapt(handlers.export));
+  app.get(at(ROUTES.list), adapt(handlers.list));
+  app.post(at(ROUTES.create), adapt(handlers.create));
+  app.get(at(ROUTES.findById), adapt(handlers.findById));
+  app.patch(at(ROUTES.update), adapt(handlers.update));
+  app.post(at(ROUTES.clone), adapt(handlers.clone));
+  app.post(at(ROUTES.softDelete), adapt(handlers.softDelete));
+  app.post(at(ROUTES.restore), adapt(handlers.restore));
+  app.delete(at(ROUTES.hardDelete), adapt(handlers.hardDelete));
+  return {
+    app,
+    handlers,
+    listen(port, host) {
+      const server = createServer(app);
+      return new Promise((resolve, reject) => {
+        server.once("error", reject);
+        const onReady = () => {
+          server.off("error", reject);
+          resolve(server);
+        };
+        if (host) server.listen(port, host, onReady);
+        else server.listen(port, onReady);
+      });
+    }
+  };
+}
+
+// src/createIntrospectedEngine.ts
+import {
+  createMaestro,
+  mergeIntrospectionWithOverrides
+} from "@maykonpaulo/maestro-core";
+var FULL_CAPABILITIES = {
+  list: true,
+  detail: true,
+  create: true,
+  update: true,
+  clone: true,
+  delete: true,
+  softDelete: true,
+  export: true,
+  bulkActions: true
+};
+var READONLY_CAPABILITIES = {
+  list: true,
+  detail: true,
+  create: false,
+  update: false,
+  clone: false,
+  delete: false,
+  softDelete: false,
+  export: true,
+  bulkActions: false
+};
+var DEFAULT_ADMIN_POLICY = {
+  roles: {
+    admin: { id: "admin", name: "Administrator", permissions: ["*"] }
+  }
+};
+function capabilitiesFor(entity, access) {
+  if (entity.capabilities) return entity.capabilities;
+  const base = access === "full" ? FULL_CAPABILITIES : READONLY_CAPABILITIES;
+  return { ...base, softDelete: access === "full" ? Boolean(entity.softDelete) : false };
+}
+async function createIntrospectedEngine(options) {
+  const datasourceId = options.datasourceId ?? "main";
+  const access = options.access ?? "full";
+  const introspection = await options.provider.introspect();
+  const overrides = options.overrides ?? { entities: [], relations: [] };
+  const config = mergeIntrospectionWithOverrides({
+    introspection,
+    overrides,
+    datasources: { [datasourceId]: options.provider },
+    defaultDatasource: datasourceId,
+    strategy: "extend",
+    operations: options.operations,
+    audit: options.audit,
+    logger: options.logger
+  });
+  config.entities = (config.entities ?? []).map((entity) => ({
+    ...entity,
+    capabilities: capabilitiesFor(entity, access)
+  }));
+  config.policies = options.policies ?? config.policies ?? DEFAULT_ADMIN_POLICY;
+  return createMaestro(config);
+}
+export {
+  applyCors,
+  createIntrospectedEngine,
+  createMaestroServer,
+  devActorResolver
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/createMaestroServer.ts","../src/expressAdapter.ts","../src/cors.ts","../src/devActorResolver.ts","../src/createIntrospectedEngine.ts"],"sourcesContent":["import { createServer, type Server } from 'node:http';\nimport express, { type Express } from 'express';\nimport { createMaestroHttpHandlers } from '@maykonpaulo/maestro-core';\nimport type {\n  MaestroEngine,\n  MaestroActorResolver,\n  MaestroHttpHandlers,\n} from '@maykonpaulo/maestro-core';\nimport { adapt } from './expressAdapter.js';\nimport { applyCors, type CorsOptions } from './cors.js';\nimport { devActorResolver } from './devActorResolver.js';\n\nexport interface CreateMaestroServerOptions {\n  /** The engine to serve. Build it from declarations (`createMaestro`) or from a live database (`createIntrospectedEngine`). */\n  engine: MaestroEngine;\n  /**\n   * Resolves the acting `Actor` for each request (authentication is the consumer's responsibility).\n   * Defaults to {@link devActorResolver} — a single admin actor, suitable only for local development.\n   */\n  actorResolver?: MaestroActorResolver;\n  /** CORS handling. `true`/omitted → permissive defaults; an object → configured; `false` → no CORS middleware. */\n  cors?: boolean | CorsOptions;\n  /** Path prefix for every route (e.g. `/api/admin`). Defaults to none. */\n  basePath?: string;\n  /**\n   * Bring your own Express app to mount the routes on (to add auth middleware, logging, other routes, etc.).\n   * When omitted, a fresh app is created with a JSON body parser and CORS.\n   */\n  app?: Express;\n}\n\nexport interface MaestroServer {\n  /** The Express app with all Maestro routes mounted. Mount extra routes/middleware before calling `listen`. */\n  app: Express;\n  /** The underlying framework-agnostic handlers, in case you want to mount a subset yourself. */\n  handlers: MaestroHttpHandlers;\n  /** Starts listening and resolves with the Node `http.Server` once bound. */\n  listen(port: number, host?: string): Promise<Server>;\n}\n\nconst ROUTES = {\n  health: '/health',\n  metadata: '/metadata',\n  entityMetadata: '/metadata/:entity',\n  operation: '/operations/:operationId',\n  export: '/entities/:entity/export',\n  list: '/entities/:entity',\n  create: '/entities/:entity',\n  findById: '/entities/:entity/:id',\n  update: '/entities/:entity/:id',\n  clone: '/entities/:entity/:id/clone',\n  softDelete: '/entities/:entity/:id/soft-delete',\n  restore: '/entities/:entity/:id/restore',\n  hardDelete: '/entities/:entity/:id',\n} as const;\n\n/**\n * Mounts the Maestro HTTP handlers on a real Express server — the turnkey layer the core deliberately\n * omits (ADR 0008). It adds only what a server needs and the core must not carry: JSON body parsing,\n * CORS, route wiring and a `listen()` lifecycle. All domain behaviour still comes from the engine.\n */\nexport function createMaestroServer(options: CreateMaestroServerOptions): MaestroServer {\n  const actorResolver = options.actorResolver ?? devActorResolver;\n  const handlers = createMaestroHttpHandlers(options.engine, { actorResolver });\n\n  const app = options.app ?? express();\n\n  if (!options.app) {\n    if (options.cors !== false) {\n      applyCors(app, typeof options.cors === 'object' ? options.cors : {});\n    }\n    app.use(express.json());\n  }\n\n  const base = options.basePath ?? '';\n  const at = (path: string): string => `${base}${path}`;\n\n  app.get(at(ROUTES.health), adapt(handlers.health));\n  app.get(at(ROUTES.metadata), adapt(handlers.getMetadata));\n  app.get(at(ROUTES.entityMetadata), adapt(handlers.getEntityMetadata));\n\n  app.post(at(ROUTES.operation), adapt(handlers.executeOperation));\n\n  // `/entities/:entity/export` must be registered before `/entities/:entity/:id` so \"export\" isn't\n  // captured as an id.\n  app.get(at(ROUTES.export), adapt(handlers.export));\n  app.get(at(ROUTES.list), adapt(handlers.list));\n  app.post(at(ROUTES.create), adapt(handlers.create));\n  app.get(at(ROUTES.findById), adapt(handlers.findById));\n  app.patch(at(ROUTES.update), adapt(handlers.update));\n  app.post(at(ROUTES.clone), adapt(handlers.clone));\n  app.post(at(ROUTES.softDelete), adapt(handlers.softDelete));\n  app.post(at(ROUTES.restore), adapt(handlers.restore));\n  app.delete(at(ROUTES.hardDelete), adapt(handlers.hardDelete));\n\n  return {\n    app,\n    handlers,\n    listen(port: number, host?: string): Promise<Server> {\n      const server = createServer(app);\n      return new Promise((resolve, reject) => {\n        server.once('error', reject);\n        const onReady = (): void => {\n          server.off('error', reject);\n          resolve(server);\n        };\n        if (host) server.listen(port, host, onReady);\n        else server.listen(port, onReady);\n      });\n    },\n  };\n}\n","import type { Request, Response } from 'express';\nimport type { MaestroHttpHandler, MaestroHttpRequest } from '@maykonpaulo/maestro-core';\n\nfunction toMaestroRequest(req: Request): MaestroHttpRequest {\n  return {\n    params: req.params as Record<string, string>,\n    query: req.query as Record<string, string | string[]>,\n    body: req.body as unknown,\n    headers: req.headers as Record<string, string | string[] | undefined>,\n    method: req.method,\n    path: req.path,\n  };\n}\n\n/**\n * Bridges a framework-agnostic `MaestroHttpHandler` (from the core) to an Express request handler.\n * The core owns the contract; this adapter is the only Express-aware surface in the package.\n */\nexport function adapt(handler: MaestroHttpHandler) {\n  return async (req: Request, res: Response): Promise<void> => {\n    const response = await handler(toMaestroRequest(req));\n\n    if (response.headers) {\n      for (const [key, value] of Object.entries(response.headers)) {\n        res.setHeader(key, value);\n      }\n    }\n\n    res.status(response.status);\n\n    if (response.body === null || response.body === undefined) {\n      res.end();\n    } else if (typeof response.body === 'string') {\n      res.send(response.body);\n    } else {\n      res.json(response.body);\n    }\n  };\n}\n","import type { Express, Request, Response, NextFunction } from 'express';\n\nexport interface CorsOptions {\n  /** Allowed origin. Defaults to `*`. Set to a concrete origin when using credentials. */\n  origin?: string;\n  /** Emit `Access-Control-Allow-Credentials: true`. Defaults to false. */\n  credentials?: boolean;\n  /** Extra request headers to allow, appended to the defaults. */\n  allowedHeaders?: string[];\n}\n\nconst DEFAULT_HEADERS = ['Content-Type', 'Authorization', 'X-Role'];\nconst ALLOWED_METHODS = 'GET,POST,PATCH,DELETE,OPTIONS';\n\n/**\n * A dependency-free CORS middleware. Kept tiny on purpose — the turnkey server should not pull an extra\n * package for a handful of headers, and a consumer with stricter needs can disable this and mount their own.\n */\nexport function applyCors(app: Express, options: CorsOptions = {}): void {\n  const headers = [...DEFAULT_HEADERS, ...(options.allowedHeaders ?? [])].join(', ');\n  app.use((req: Request, res: Response, next: NextFunction): void => {\n    res.setHeader('Access-Control-Allow-Origin', options.origin ?? '*');\n    res.setHeader('Access-Control-Allow-Methods', ALLOWED_METHODS);\n    res.setHeader('Access-Control-Allow-Headers', headers);\n    if (options.credentials) res.setHeader('Access-Control-Allow-Credentials', 'true');\n    if (req.method === 'OPTIONS') {\n      res.status(204).end();\n      return;\n    }\n    next();\n  });\n}\n","import type { MaestroActorResolver } from '@maykonpaulo/maestro-core';\n\n/**\n * The default resolver used when `createMaestroServer` is called without one. It grants every request a\n * single admin actor — convenient for local development and demos, and **never** appropriate for\n * production. In production the consumer supplies its own resolver (deriving the actor from a JWT, cookie\n * or session), keeping authentication the consumer's responsibility (ADR 0008, DA-18).\n */\nexport const devActorResolver: MaestroActorResolver = async () => ({\n  actor: {\n    id: 'dev-admin',\n    type: 'user',\n    name: 'Development Admin',\n    roles: ['admin'],\n  },\n});\n","import {\n  createMaestro,\n  mergeIntrospectionWithOverrides,\n} from '@maykonpaulo/maestro-core';\nimport type {\n  MaestroEngine,\n  IntrospectionProvider,\n  DatasourceProvider,\n  EntityCapabilities,\n  EntitySchema,\n  RbacPolicy,\n  LoadedConfig,\n  OperationDef,\n  AuditRepository,\n  Logger,\n} from '@maykonpaulo/maestro-core';\n\n/** Access level applied to entities discovered by introspection. */\nexport type IntrospectedAccess = 'full' | 'readonly';\n\nexport interface CreateIntrospectedEngineOptions {\n  /**\n   * A live provider that can both describe the database (`introspect`) and operate it (`list/create/...`).\n   * The MongoDB, SQL, and other official providers implement both interfaces on a single instance.\n   */\n  provider: IntrospectionProvider & DatasourceProvider;\n  /** Datasource id the discovered entities are bound to. Defaults to `main`. */\n  datasourceId?: string;\n  /**\n   * `full` (default) enables every capability on discovered entities, turning the engine into a complete\n   * database manipulator. `readonly` enables only list/detail/export — a safe way to browse a database\n   * without any risk of mutating it.\n   */\n  access?: IntrospectedAccess;\n  /**\n   * Optional curated overlay (labels, extra fields, relations, RBAC) merged over the introspected schema\n   * via the core `HybridLoader`. Entities you curate here keep their own explicit `capabilities`.\n   */\n  overrides?: LoadedConfig;\n  /**\n   * RBAC policy for the engine. When omitted, a default `admin` role with `['*']` is used — appropriate\n   * for a single platform operator and meant to be replaced with a real policy in multi-role deployments.\n   */\n  policies?: RbacPolicy;\n  operations?: OperationDef[];\n  audit?: AuditRepository;\n  logger?: Logger;\n}\n\nconst FULL_CAPABILITIES: EntityCapabilities = {\n  list: true,\n  detail: true,\n  create: true,\n  update: true,\n  clone: true,\n  delete: true,\n  softDelete: true,\n  export: true,\n  bulkActions: true,\n};\n\nconst READONLY_CAPABILITIES: Partial<EntityCapabilities> = {\n  list: true,\n  detail: true,\n  create: false,\n  update: false,\n  clone: false,\n  delete: false,\n  softDelete: false,\n  export: true,\n  bulkActions: false,\n};\n\nconst DEFAULT_ADMIN_POLICY: RbacPolicy = {\n  roles: {\n    admin: { id: 'admin', name: 'Administrator', permissions: ['*'] },\n  },\n};\n\n/**\n * Resolves the capabilities for one entity. Curated entities (an override that set `capabilities`\n * explicitly) are respected as-is; entities discovered by introspection get the access-level defaults.\n * The `softDelete` capability is only ever enabled when the entity actually declares a soft-delete field,\n * since the engine throws a configuration error otherwise.\n */\nfunction capabilitiesFor(entity: EntitySchema, access: IntrospectedAccess): Partial<EntityCapabilities> {\n  if (entity.capabilities) return entity.capabilities;\n  const base = access === 'full' ? FULL_CAPABILITIES : READONLY_CAPABILITIES;\n  return { ...base, softDelete: access === 'full' ? Boolean(entity.softDelete) : false };\n}\n\n/**\n * Builds a `MaestroEngine` directly from a live database, with no per-entity declaration required\n * (ADR 0008, DA-17). It introspects the provider, turns every discovered collection/table into a\n * manipulable entity, and — unlike `createMaestroFromIntrospection`, whose entities are read-only by\n * default — enables write capabilities according to `access`, so \"point at the database and manipulate\n * everything\" works out of the box.\n *\n * Uses only public core exports (`introspect` → `mergeIntrospectionWithOverrides` → `createMaestro`).\n */\nexport async function createIntrospectedEngine(\n  options: CreateIntrospectedEngineOptions,\n): Promise<MaestroEngine> {\n  const datasourceId = options.datasourceId ?? 'main';\n  const access = options.access ?? 'full';\n\n  const introspection = await options.provider.introspect();\n  const overrides: LoadedConfig = options.overrides ?? { entities: [], relations: [] };\n\n  const config = mergeIntrospectionWithOverrides({\n    introspection,\n    overrides,\n    datasources: { [datasourceId]: options.provider },\n    defaultDatasource: datasourceId,\n    strategy: 'extend',\n    operations: options.operations,\n    audit: options.audit,\n    logger: options.logger,\n  });\n\n  config.entities = (config.entities ?? []).map((entity) => ({\n    ...entity,\n    capabilities: capabilitiesFor(entity, access),\n  }));\n\n  config.policies = options.policies ?? config.policies ?? DEFAULT_ADMIN_POLICY;\n\n  return createMaestro(config);\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@maykonpaulo/maestro-server",
+  "version": "0.1.0-next.1",
+  "description": "Turnkey HTTP server for @maykonpaulo/maestro-core — mounts the framework-agnostic Maestro HTTP handlers on a real Express server and turns any live datasource provider into a full, governed admin over the whole database (ADR 0008). The core stays server-free; this sibling package is the batteries-included layer.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@maykonpaulo/maestro-core": "0.7.0-next.2"
+  },
+  "dependencies": {
+    "express": "^4.19.2"
+  },
+  "devDependencies": {
+    "@types/express": "^4.17.21",
+    "@types/node": "^22.0.0",
+    "mongodb": "^7.4.0",
+    "mongodb-memory-server": "^11.2.0",
+    "rimraf": "^6.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.6.0",
+    "vitest": "^2.0.0",
+    "@maykonpaulo/maestro-core": "0.7.0-next.2",
+    "@maykonpaulo/maestro-provider-mongodb": "1.0.0-next.1"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "test:integration": "vitest run --config vitest.integration.config.ts",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src tests",
+    "clean": "rimraf dist"
+  }
+}