@moshaver/cmb-starter 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mobin Karam
+
+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,73 @@
+# @moshaver/cmb-starter
+
+[English](#english) | [فارسی](#فارسی)
+
+## English
+
+`@moshaver/cmb-starter` creates a framework-neutral CMB runtime from one small
+configuration object. It resolves module dependencies, exposes lifecycle and
+readiness APIs, and leaves HTTP transport, database drivers, secrets, routes,
+and product policy to the host application.
+
+```bash
+npm install @moshaver/cmb-starter
+```
+
+Create one `cmb.config.cjs` file:
+
+```js
+module.exports = {
+  serviceName: "notes-api",
+  modules: ["auth", "authorization", "notifications", "realtime"],
+};
+```
+
+Load it at the application's composition root:
+
+```js
+const config = require("./cmb.config.cjs");
+const { createCmbRuntime } = require("@moshaver/cmb-starter");
+
+const cmb = createCmbRuntime(config);
+await cmb.start();
+await cmb.ready();
+```
+
+Dependencies such as `identity` and `tenancy` are resolved automatically. Add
+your own product module descriptors through `registrations`; keep product
+routes, roles, storage adapters, and secrets outside this package.
+
+## فارسی
+
+پکیج `@moshaver/cmb-starter` با یک شیء پیکربندی کوچک، runtime مستقل از
+فریم‌ورک CMB را می‌سازد. وابستگی ماژول‌ها، چرخهٔ اجرا و وضعیت آماده‌بودن را
+مدیریت می‌کند؛ اما HTTP، درایور پایگاه‌داده، رازها، مسیرها و قوانین محصول
+همچنان مسئولیت برنامهٔ میزبان هستند.
+
+```bash
+npm install @moshaver/cmb-starter
+```
+
+یک فایل `cmb.config.cjs` بسازید:
+
+```js
+module.exports = {
+  serviceName: "notes-api",
+  modules: ["auth", "authorization", "notifications", "realtime"],
+};
+```
+
+سپس آن را در composition root برنامه بارگذاری کنید:
+
+```js
+const config = require("./cmb.config.cjs");
+const { createCmbRuntime } = require("@moshaver/cmb-starter");
+
+const cmb = createCmbRuntime(config);
+await cmb.start();
+await cmb.ready();
+```
+
+وابستگی‌هایی مانند `identity` و `tenancy` خودکار حل می‌شوند. descriptorهای
+محصول خود را با `registrations` اضافه کنید و مسیرها، نقش‌ها، adapterهای ذخیره‌سازی
+و رازهای محصول را بیرون از این پکیج نگه دارید.

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@moshaver/cmb-starter",
+  "version": "0.1.0",
+  "description": "Composable Modular Backend starter primitives.",
+  "type": "commonjs",
+  "main": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "exports": {
+    ".": {
+      "require": "./src/index.js",
+      "types": "./src/index.d.ts"
+    }
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "cmb",
+    "modular-backend",
+    "backend",
+    "framework-agnostic",
+    "starter"
+  ],
+  "engines": {
+    "node": ">=22.13.0 <23"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Mobin-Karam/moshaver.git",
+    "directory": "packages/cmb/starter"
+  },
+  "bugs": {
+    "url": "https://github.com/Mobin-Karam/moshaver/issues"
+  },
+  "homepage": "https://github.com/Mobin-Karam/moshaver/tree/main/packages/cmb",
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "sideEffects": false,
+  "dependencies": {
+    "@moshaver/cmb-activity": "^0.1.0",
+    "@moshaver/cmb-auth": "^0.1.0",
+    "@moshaver/cmb-authorization": "^0.1.0",
+    "@moshaver/cmb-data-transfer": "^0.1.0",
+    "@moshaver/cmb-health": "^0.1.0",
+    "@moshaver/cmb-identity": "^0.1.0",
+    "@moshaver/cmb-infrastructure": "^0.1.0",
+    "@moshaver/cmb-kernel": "^0.1.0",
+    "@moshaver/cmb-notifications": "^0.1.0",
+    "@moshaver/cmb-persistence": "^0.1.0",
+    "@moshaver/cmb-realtime": "^0.1.0",
+    "@moshaver/cmb-system": "^0.1.0",
+    "@moshaver/cmb-tenancy": "^0.1.0"
+  }
+}

package/src/index.d.ts

@@ -0,0 +1,27 @@
+import type { CmbModuleDescriptor, CmbModuleRegistration, CmbModuleRegistry } from "@moshaver/cmb-kernel";
+import type { CmbHealthService } from "@moshaver/cmb-health";
+
+export const STARTER_MODULE: CmbModuleDescriptor;
+export const builtInModules: Readonly<Record<string, CmbModuleDescriptor>>;
+
+export type CmbStarterConfig = Readonly<{
+  serviceName?: string;
+  modules?: readonly (keyof typeof builtInModules)[];
+  registrations?: readonly CmbModuleDescriptor[] | readonly CmbModuleRegistration[];
+}>;
+
+export function normalizeConfig(input?: CmbStarterConfig): Readonly<{
+  serviceName: string;
+  modules: readonly string[];
+  registrations: readonly (CmbModuleDescriptor | CmbModuleRegistration)[];
+}>;
+
+export function createCmbRuntime(config?: CmbStarterConfig): Readonly<{
+  config: ReturnType<typeof normalizeConfig>;
+  registry: CmbModuleRegistry;
+  health: CmbHealthService;
+  metadata(): readonly CmbModuleDescriptor[];
+  ready(): ReturnType<CmbHealthService["ready"]>;
+  start(context?: Record<string, unknown>): ReturnType<CmbModuleRegistry["start"]>;
+  stop(context?: Record<string, unknown>): ReturnType<CmbModuleRegistry["stop"]>;
+}>;

package/src/index.js

@@ -0,0 +1,94 @@
+"use strict";
+
+const { CmbModuleRegistry, defineModule } = require("@moshaver/cmb-kernel");
+const { HEALTH_MODULE, CmbHealthService } = require("@moshaver/cmb-health");
+const { PERSISTENCE_MODULE } = require("@moshaver/cmb-persistence");
+const { INFRASTRUCTURE_MODULE } = require("@moshaver/cmb-infrastructure");
+const { REALTIME_MODULE } = require("@moshaver/cmb-realtime");
+const { IDENTITY_MODULE } = require("@moshaver/cmb-identity");
+const { TENANCY_MODULE } = require("@moshaver/cmb-tenancy");
+const { SYSTEM_MODULE } = require("@moshaver/cmb-system");
+const { AUTH_MODULE } = require("@moshaver/cmb-auth");
+const { AUTHORIZATION_MODULE } = require("@moshaver/cmb-authorization");
+const { NOTIFICATIONS_MODULE } = require("@moshaver/cmb-notifications");
+const { ACTIVITY_MODULE } = require("@moshaver/cmb-activity");
+const { DATA_TRANSFER_MODULE } = require("@moshaver/cmb-data-transfer");
+
+const STARTER_MODULE = defineModule({
+  id: "starter",
+  version: "0.1.0",
+  kind: "platform",
+  dependencies: [
+    "activity", "auth", "authorization", "data-transfer", "health", "identity",
+    "infrastructure", "kernel", "notifications", "persistence", "realtime", "system", "tenancy",
+  ],
+  provides: ["cmb.runtime"],
+});
+
+const builtInModules = Object.freeze({
+  health: HEALTH_MODULE,
+  persistence: PERSISTENCE_MODULE,
+  infrastructure: INFRASTRUCTURE_MODULE,
+  realtime: REALTIME_MODULE,
+  identity: IDENTITY_MODULE,
+  tenancy: TENANCY_MODULE,
+  system: SYSTEM_MODULE,
+  auth: AUTH_MODULE,
+  authorization: AUTHORIZATION_MODULE,
+  notifications: NOTIFICATIONS_MODULE,
+  activity: ACTIVITY_MODULE,
+  "data-transfer": DATA_TRANSFER_MODULE,
+});
+
+function normalizeConfig(input = {}) {
+  if (!input || typeof input !== "object" || Array.isArray(input)) {
+    throw new TypeError("CMB configuration must be an object.");
+  }
+  const serviceName = String(input.serviceName ?? "cmb-service").trim();
+  if (!serviceName) throw new TypeError("config.serviceName must not be empty.");
+  const registrations = input.registrations ?? [];
+  if (!Array.isArray(registrations)) throw new TypeError("config.registrations must be an array.");
+  const registeredIds = new Set(registrations.map((entry) => entry?.descriptor?.id ?? entry?.id));
+  const modules = input.modules ?? ["health"];
+  if (!Array.isArray(modules) || modules.some((id) => typeof id !== "string" || (!builtInModules[id] && !registeredIds.has(id)))) {
+    throw new TypeError("config.modules must contain built-in or registered CMB module ids.");
+  }
+  return Object.freeze({ serviceName, modules: [...new Set(["health", ...modules])], registrations });
+}
+
+function createCmbRuntime(config) {
+  const normalized = normalizeConfig(config);
+  const registrations = [...Object.values(builtInModules), ...normalized.registrations];
+  const registry = new CmbModuleRegistry(registrations);
+  const descriptors = new Map(
+    registrations.map((entry) => {
+      const descriptor = entry?.descriptor ?? entry;
+      return [descriptor.id, descriptor];
+    }),
+  );
+  const enabled = new Set(["kernel"]);
+  const include = (id) => {
+    if (enabled.has(id)) return;
+    const descriptor = descriptors.get(id);
+    if (!descriptor) throw new Error(`CMB module ${id} is not registered.`);
+    enabled.add(id);
+    for (const dependency of descriptor.dependencies ?? []) include(dependency);
+  };
+  for (const id of normalized.modules) include(id);
+  const enabledModules = [...enabled];
+  const health = new CmbHealthService({
+    serviceName: normalized.serviceName,
+    probes: [{ name: "modules", check: () => registry.resolve(enabledModules) }],
+  });
+  return Object.freeze({
+    config: normalized,
+    registry,
+    health,
+    metadata: () => registry.metadata(enabledModules),
+    ready: () => health.ready(),
+    start: async (context = {}) => registry.start({ ...context, health }, enabledModules),
+    stop: async (context = {}) => registry.stop({ ...context, health }),
+  });
+}
+
+module.exports = { STARTER_MODULE, builtInModules, normalizeConfig, createCmbRuntime };