@specverse/engines 6.5.4 → 6.7.8

package/dist/libs/instance-factories/applications/templates/generic/backend-package-json-generator.js

@@ -1,6 +1,27 @@
+function resolveOrmName(manifest) {
+  if (!manifest) return "PrismaORM";
+  const inner = manifest.manifests ? Object.values(manifest.manifests)[0] : manifest;
+  if (!inner) return "PrismaORM";
+  const caps = Array.isArray(inner.capabilityMappings) ? inner.capabilityMappings : [];
+  const ormCap = caps.find((m) => m?.capability === "orm.client") || caps.find((m) => m?.capability === "orm.schema");
+  if (ormCap) return ormCap.implementation || ormCap.instanceFactory || "PrismaORM";
+  return inner.defaultMappings?.orm || "PrismaORM";
+}
 function generateBackendPackageJson(context) {
-  const { spec } = context;
+  const { spec, manifest } = context;
   const appName = (spec.metadata?.component || "app").toLowerCase().replace(/\s+/g, "-");
+  const orm = resolveOrmName(manifest);
+  const isMongoNative = orm === "MongoDBNativeDriver";
+  const dbScripts = isMongoNative ? {} : {
+    "db:setup": "prisma generate && prisma db push",
+    "db:generate": "prisma generate",
+    "db:push": "prisma db push",
+    "db:migrate": "prisma migrate dev",
+    "db:studio": "prisma studio",
+    "db:seed": "tsx prisma/seed.ts"
+  };
+  const ormDeps = isMongoNative ? { "mongodb": "^6.3.0" } : { "@prisma/client": "^5.7.0" };
+  const ormDevDeps = isMongoNative ? {} : { "prisma": "^5.7.0" };
   const pkg = {
     name: `${appName}-backend`,
     version: spec.metadata?.version || "1.0.0",
@@ -18,13 +39,8 @@ function generateBackendPackageJson(context) {
       "build:watch": "tsc --watch",
       // Production
       "start": "node dist/main.js",
-      // Database
-      "db:setup": "prisma generate && prisma db push",
-      "db:generate": "prisma generate",
-      "db:push": "prisma db push",
-      "db:migrate": "prisma migrate dev",
-      "db:studio": "prisma studio",
-      "db:seed": "tsx prisma/seed.ts",
+      // Database (ORM-specific; empty for native driver)
+      ...dbScripts,
       // Testing
       "test": "vitest run --passWithNoTests",
       "test:watch": "vitest watch",
@@ -36,7 +52,7 @@ function generateBackendPackageJson(context) {
       "typecheck": "tsc --noEmit"
     },
     dependencies: {
-      "@prisma/client": "^5.7.0",
+      ...ormDeps,
       "fastify": "^5.8.3",
       "@fastify/cors": "^10.0.0",
       "@fastify/helmet": "^12.0.0",
@@ -51,7 +67,7 @@ function generateBackendPackageJson(context) {
       "typescript": "^5.3.0",
       "@types/node": "^20.10.0",
       "tsx": "^4.7.0",
-      "prisma": "^5.7.0",
+      ...ormDevDeps,
       "vitest": "^3.0.0",
       "@vitest/coverage-v8": "^3.0.0",
       "eslint": "^9.0.0",

package/dist/libs/instance-factories/controllers/templates/fastify/server-generator.js

@@ -39,7 +39,7 @@ function generateFastifyServer(context) {
 // workspace before running the script.
 import { config as loadEnv } from 'dotenv';
 import { existsSync } from 'fs';
-import { resolve as resolvePath, dirname, join } from 'path';
+import { dirname, join } from 'path';
 import { fileURLToPath } from 'url';
 {
   let dir = dirname(fileURLToPath(import.meta.url));

package/dist/libs/instance-factories/services/mongodb-native-services.yaml

@@ -0,0 +1,84 @@
+name: MongoDBNativeDriver
+version: "1.0.0"
+category: service
+description: "Business logic services using the native MongoDB driver for collection access (no ORM layer)"
+
+metadata:
+  author: "SpecVerse Team"
+  license: "MIT"
+  tags: [services, business-logic, mongodb, native-driver, controllers]
+
+compatibility:
+  specverse: ">=5.0.0"
+  node: ">=18.0.0"
+
+# With the MongoDB native driver, collection access IS the data layer — there
+# is no ORM layer to swap in independently. So this single factory provides
+# both the "orm.client" capability AND the service-layer capabilities.
+capabilities:
+  provides:
+    - "orm.schema"     # Emits the MongoDB client connector (the client IS the schema layer)
+    - "orm.client"
+    - "orm.mongodb.native"
+    - "service.controller"
+    - "service.business"
+    - "service.crud"
+  requires:
+    - "storage.database.document"
+
+technology:
+  runtime: "node"
+  language: "typescript"
+  orm: "mongodb-native"
+  version: "^6.0.0"
+
+dependencies:
+  runtime:
+    - name: "mongodb"
+      version: "^6.3.0"
+
+  dev:
+    - name: "@types/node"
+      version: "^20.8.0"
+    - name: "typescript"
+      version: "^5.2.0"
+
+codeTemplates:
+  # `schema` is the orm.schema-capability slot the realize engine drives for
+  # ORM-side artifacts. With Prisma this emits `schema.prisma`; with the
+  # MongoDB native driver there is no separate db-schema artifact, so this
+  # slot emits the singleton client connector instead — same intent
+  # ("how does the app reach the data layer"), different physical output.
+  schema:
+    engine: typescript
+    generator: "libs/instance-factories/services/templates/mongodb-native/client-generator.ts"
+    outputPattern: "{backendDir}/src/db/mongoClient.ts"
+
+  controllers:
+    engine: typescript
+    generator: "libs/instance-factories/services/templates/mongodb-native/controller-generator.ts"
+    outputPattern: "{backendDir}/src/controllers/{model}Controller.ts"
+
+  services:
+    engine: typescript
+    generator: "libs/instance-factories/services/templates/mongodb-native/service-generator.ts"
+    outputPattern: "{backendDir}/src/services/{service}.ts"
+
+configuration:
+  outputStructure: "monorepo"
+  backendDir: "backend"
+  collectionNaming: "lowercase-pluralized"  # User → users, OrderItem → orderitems
+  validation: true
+  eventPublishing: true
+  errorHandling: "throw"
+
+requirements:
+  dependencies:
+    npm:
+      dependencies:
+        "mongodb": "^6.3.0"
+  environment:
+    - name: "MONGODB_URI"
+      description: "MongoDB connection string (e.g. mongodb://localhost:27017/myapp)"
+      required: true
+  configuration: {}

package/dist/libs/instance-factories/services/templates/mongodb-native/client-generator.js

@@ -0,0 +1,43 @@
+function generateMongoClient(_context) {
+  return `/**
+ * MongoDB native driver \u2014 singleton client + helpers.
+ *
+ * Picks up MONGODB_URI / MONGODB_DB from the environment. The client is
+ * lazily initialised on first use and reused across requests; \`disconnect\`
+ * is exposed for graceful-shutdown wiring.
+ */
+import { MongoClient, type Db, type Collection, type Document } from 'mongodb';
+
+const uri = process.env.MONGODB_URI || 'mongodb://localhost:27017';
+const dbName = process.env.MONGODB_DB || 'specverse';
+
+let client: MongoClient | null = null;
+let database: Db | null = null;
+
+export async function getDb(): Promise<Db> {
+  if (database) return database;
+  client = new MongoClient(uri);
+  await client.connect();
+  database = client.db(dbName);
+  return database;
+}
+
+export async function getCollection<T extends Document = Document>(
+  name: string,
+): Promise<Collection<T>> {
+  const db = await getDb();
+  return db.collection<T>(name);
+}
+
+export async function disconnect(): Promise<void> {
+  if (client) {
+    await client.close();
+    client = null;
+    database = null;
+  }
+}
+`;
+}
+export {
+  generateMongoClient as default
+};

package/dist/libs/instance-factories/services/templates/mongodb-native/controller-generator.js

@@ -0,0 +1,252 @@
+import { buildTransitionMap, isAutoField } from "@specverse/types/spec-rules";
+function generateMongoNativeController(context) {
+  const { controller, model } = context;
+  if (!controller) throw new Error("Controller is required in template context");
+  if (!model) throw new Error("Model is required for controller generation");
+  const controllerName = controller.name;
+  const modelName = model.name;
+  const modelVar = lowerFirst(modelName);
+  const collection = collectionName(model);
+  const curedOps = controller.cured || {};
+  const customActions = generateCustomActions(controller);
+  const validate = generateValidateMethod(model, modelName);
+  const create = curedOps.create ? generateCreateMethod(model, modelName, modelVar, collection) : "";
+  const retrieve = curedOps.retrieve ? generateRetrieveMethod(modelName, modelVar, collection) : "";
+  const update = curedOps.update ? generateUpdateMethod(modelName, modelVar, collection) : "";
+  const evolve = curedOps.evolve ? generateEvolveMethod(model, modelName, modelVar, collection) : "";
+  const del = curedOps.delete ? generateDeleteMethod(modelName, modelVar, collection) : "";
+  const hasEventPublishing = curedOps.create || curedOps.update || curedOps.evolve || curedOps.delete;
+  return `/**
+ * ${controllerName}
+ * Model-specific business logic for ${modelName} (MongoDB native driver)
+ * ${controller.description || ""}
+ */
+import { ObjectId, type Filter, type Document } from 'mongodb';
+import { getCollection } from '../db/mongoClient.js';
+${hasEventPublishing ? `import { eventBus } from '../events/eventBus.js';` : ""}
+
+const COLLECTION_NAME = '${collection}';
+
+/** Parse an id string to the value the collection expects: ObjectId for
+ * 24-hex-character ids, otherwise pass-through (UUIDs, slugs, ints-as-string). */
+function parseId(id: string): ObjectId | string {
+  if (typeof id === 'string' && /^[a-fA-F0-9]{24}$/.test(id)) return new ObjectId(id);
+  return id;
+}
+
+/** _id-aware filter builder. */
+function byId(id: string): Filter<Document> {
+  return { _id: parseId(id) as any };
+}
+
+export class ${controllerName} {
+${validate}
+${create}
+${retrieve}
+${update}
+${evolve}
+${del}
+${customActions.code}
+}
+
+export const ${modelVar}Controller = new ${controllerName}();
+export default ${modelVar}Controller;
+`;
+}
+function lowerFirst(s) {
+  return s.charAt(0).toLowerCase() + s.slice(1);
+}
+function collectionName(model) {
+  if (model?.storage?.collection) return String(model.storage.collection);
+  return model.name.toLowerCase() + "s";
+}
+function generateValidateMethod(model, modelName) {
+  return `
+  /**
+   * Validate ${modelName} data \u2014 runs before create / update / evolve.
+   */
+  public validate(
+    _data: any,
+    _context: { operation: 'create' | 'update' | 'evolve' }
+  ): { valid: boolean; errors: string[] } {
+    const errors: string[] = [];
+${generateValidationLogic(model)}
+    return { valid: errors.length === 0, errors };
+  }
+`;
+}
+function generateValidationLogic(model) {
+  if (!model.attributes) return "    // No validation rules defined";
+  const attrList = Array.isArray(model.attributes) ? model.attributes.map((a) => [a.name, a]) : Object.entries(model.attributes);
+  const out = [];
+  attrList.forEach(([name, attr]) => {
+    if (attr.required && !isAutoField(name, attr)) {
+      out.push(`    if (_context.operation === 'create' && !_data.${name}) errors.push('${name} is required');`);
+    }
+    if (attr.type === "String" || attr.type === "string") {
+      if (attr.min) out.push(`    if (_data.${name} && _data.${name}.length < ${attr.min}) errors.push('${name} must be at least ${attr.min} characters');`);
+      if (attr.max) out.push(`    if (_data.${name} && _data.${name}.length > ${attr.max}) errors.push('${name} must be at most ${attr.max} characters');`);
+    }
+    if (attr.values && Array.isArray(attr.values)) {
+      const values = attr.values.map((v) => `'${v}'`).join(", ");
+      out.push(`    if (_data.${name} && ![${values}].includes(_data.${name})) errors.push('${name} must be one of: ${attr.values.join(", ")}');`);
+    }
+    if (attr.format === "email") {
+      out.push(`    if (_data.${name} && !/^[^\\s@]+@[^\\s@]+\\.[^\\s@]+$/.test(_data.${name})) errors.push('${name} must be a valid email address');`);
+    }
+  });
+  return out.join("\n") || "    // No validation rules defined";
+}
+function generateCreateMethod(model, modelName, modelVar, collection) {
+  return `
+  /**
+   * Create a new ${modelName}.
+   */
+  public async create(data: any): Promise<any> {
+    const validation = this.validate(data, { operation: 'create' });
+    if (!validation.valid) throw new Error(\`Validation failed: \${validation.errors.join(', ')}\`);
+
+    const collection = await getCollection(COLLECTION_NAME);
+    const result = await collection.insertOne({ ...data });
+    const ${modelVar} = { _id: result.insertedId, ...data };
+
+    await eventBus.publish('${modelName}Created', { ...${modelVar}, timestamp: new Date().toISOString() } as any);
+    return ${modelVar};
+  }
+`;
+}
+function generateRetrieveMethod(modelName, modelVar, collection) {
+  return `
+  /**
+   * Retrieve ${modelName} by id. Returns null when not found.
+   */
+  public async retrieve(id: string): Promise<any | null> {
+    const collection = await getCollection(COLLECTION_NAME);
+    return await collection.findOne(byId(id));
+  }
+
+  /**
+   * Retrieve a page of ${modelName}s.
+   */
+  public async retrieveAll(options: { skip?: number; take?: number } = {}): Promise<any[]> {
+    const collection = await getCollection(COLLECTION_NAME);
+    const cursor = collection.find({});
+    if (options.skip) cursor.skip(options.skip);
+    if (options.take) cursor.limit(options.take);
+    return await cursor.toArray();
+  }
+`;
+}
+function generateUpdateMethod(modelName, modelVar, collection) {
+  return `
+  /**
+   * Update ${modelName}.
+   */
+  public async update(id: string, data: any): Promise<any> {
+    const validation = this.validate(data, { operation: 'update' });
+    if (!validation.valid) throw new Error(\`Validation failed: \${validation.errors.join(', ')}\`);
+
+    // Strip nested objects + id \u2014 only scalar fields are written.
+    const updateData: any = {};
+    for (const [key, value] of Object.entries(data)) {
+      if (key === 'id' || key === '_id') continue;
+      if (Array.isArray(value)) continue;
+      if (value !== null && typeof value === 'object' && !(value instanceof Date)) continue;
+      updateData[key] = value;
+    }
+
+    const collection = await getCollection(COLLECTION_NAME);
+    await collection.updateOne(byId(id), { $set: updateData });
+    const ${modelVar} = await collection.findOne(byId(id));
+    if (!${modelVar}) throw new Error('${modelName} not found after update');
+
+    await eventBus.publish('${modelName}Updated', { ...${modelVar}, timestamp: new Date().toISOString() } as any);
+    return ${modelVar};
+  }
+`;
+}
+function generateEvolveMethod(model, modelName, modelVar, collection) {
+  const lifecycles = Array.isArray(model.lifecycles) ? model.lifecycles : model.lifecycles ? Object.entries(model.lifecycles).map(([name, lc]) => ({ name, ...lc })) : [];
+  const lifecycle = lifecycles[0];
+  const lifecycleName = lifecycle?.name || "status";
+  const validTransitions = lifecycle ? buildTransitionMap(lifecycle) : {};
+  const states = lifecycle?.states && lifecycle.states.length > 0 ? lifecycle.states.map((s) => typeof s === "string" ? s : s.name) : Array.from(/* @__PURE__ */ new Set([
+    ...Object.keys(validTransitions),
+    ...Object.values(validTransitions).flat()
+  ]));
+  return `
+  /**
+   * Evolve ${modelName} through lifecycle "${lifecycleName}"
+   * States: ${states.join(" \u2192 ") || "(none declared)"}
+   */
+  public async evolve(id: string, data: any): Promise<any> {
+    const collection = await getCollection(COLLECTION_NAME);
+    const current = await collection.findOne(byId(id));
+    if (!current) throw new Error('${modelName} not found');
+
+    const targetLifecycle = data?.lifecycleName || '${lifecycleName}';
+    const targetState = data?.toState ?? data?.state ?? data?.[targetLifecycle];
+    if (!targetState) throw new Error('evolve requires toState (or ${lifecycleName}) in the request body');
+
+    ${states.length > 0 ? `
+    const currentState = (current as any)[targetLifecycle];
+    const validTransitions: Record<string, string[]> = ${JSON.stringify(validTransitions)};
+    const allowed = validTransitions[currentState] || [];
+    if (!allowed.includes(targetState)) {
+      throw new Error(\`Invalid transition: \${currentState} \u2192 \${targetState}. Allowed: \${allowed.join(', ') || 'none'}\`);
+    }
+    ` : ""}
+
+    await collection.updateOne(byId(id), { $set: { [targetLifecycle]: targetState } });
+    const ${modelVar} = await collection.findOne(byId(id));
+    if (!${modelVar}) throw new Error('${modelName} not found after evolve');
+
+    await eventBus.publish('${modelName}Evolved', { ...${modelVar}, timestamp: new Date().toISOString() } as any);
+    return ${modelVar};
+  }
+`;
+}
+function generateDeleteMethod(modelName, modelVar, collection) {
+  return `
+  /**
+   * Delete ${modelName}.
+   */
+  public async delete(id: string): Promise<void> {
+    const collection = await getCollection(COLLECTION_NAME);
+    const ${modelVar} = await collection.findOne(byId(id));
+    await collection.deleteOne(byId(id));
+    if (${modelVar}) {
+      await eventBus.publish('${modelName}Deleted', { ...${modelVar}, timestamp: new Date().toISOString() } as any);
+    }
+  }
+`;
+}
+function generateCustomActions(controller) {
+  if (!controller.actions || Object.keys(controller.actions).length === 0) {
+    return { code: "" };
+  }
+  const out = [];
+  for (const [actionName, action] of Object.entries(controller.actions)) {
+    const stepsHeader = action.steps && action.steps.length > 0 ? action.steps.map((s) => `   *   - ${typeof s === "string" ? s : s.action || JSON.stringify(s)}`).join("\n") : "   *   (no spec steps declared)";
+    out.push(`
+  /**
+   * ${actionName}
+   * ${action.description || ""}
+   *
+   * Spec steps:
+${stepsHeader}
+   */
+  public async ${actionName}(_args: any = {}): Promise<any> {
+    // TODO (#43F): translate spec steps into native MongoDB driver calls
+    // via a mongodb-native step-conventions library (mirror of the prisma
+    // one). For now this is a stub so realize completes and the action
+    // surface is callable for parity tests.
+    throw new Error('${controller.name}.${actionName} is not implemented');
+  }
+`);
+  }
+  return { code: out.join("\n") };
+}
+export {
+  generateMongoNativeController as default
+};

package/dist/libs/instance-factories/services/templates/mongodb-native/service-generator.js

@@ -0,0 +1,64 @@
+function generateMongoNativeService(context) {
+  const { service } = context;
+  if (!service) throw new Error("Service is required in template context");
+  const serviceName = service.name;
+  const operationsCode = generateOperations(service);
+  const usesDb = /\bgetDb\b|\bgetCollection\b/.test(operationsCode);
+  const hasEvents = service.publishes && service.publishes.length > 0 || service.subscribes && service.subscribes.length > 0;
+  return `/**
+ * ${serviceName}
+ * Abstract business logic service (MongoDB native driver)
+ * ${service.description || ""}
+ */
+${usesDb ? `import { getDb, getCollection } from '../db/mongoClient.js';` : ""}
+${hasEvents ? `import { eventBus } from '../events/eventBus.js';` : ""}
+
+export class ${serviceName} {
+${operationsCode}
+}
+
+const ${lowerFirst(serviceName)} = new ${serviceName}();
+export const ${lowerFirst(serviceName)}Instance = ${lowerFirst(serviceName)};
+export default ${lowerFirst(serviceName)};
+`;
+}
+function lowerFirst(s) {
+  return s.charAt(0).toLowerCase() + s.slice(1);
+}
+function generateOperations(service) {
+  const ops = service.operations;
+  if (!ops || Array.isArray(ops) && ops.length === 0 || !Array.isArray(ops) && Object.keys(ops).length === 0) {
+    return `
+  /**
+   * Default service entrypoint \u2014 replace with real operations once declared
+   * on the service's spec.
+   */
+  public async execute(_params: any = {}): Promise<any> {
+    throw new Error('${service.name}.execute is not implemented');
+  }
+`;
+  }
+  const entries = Array.isArray(ops) ? ops.map((op) => [op.name, op]) : Object.entries(ops);
+  return entries.map(([name, op]) => generateOperation(name, op, service.name)).join("\n");
+}
+function generateOperation(operationName, operation, serviceName) {
+  const stepsHeader = operation.steps && operation.steps.length > 0 ? operation.steps.map((s) => `   *   - ${typeof s === "string" ? s : s.action || JSON.stringify(s)}`).join("\n") : "   *   (no spec steps declared)";
+  return `
+  /**
+   * ${operationName}
+   * ${operation.description || ""}
+   *
+   * Spec steps:
+${stepsHeader}
+   */
+  public async ${operationName}(_args: any = {}): Promise<any> {
+    // TODO (#43 follow-up): translate spec steps into native MongoDB driver
+    // calls. For now this is a stub so realize completes and the service
+    // surface is callable for parity tests.
+    throw new Error('${serviceName}.${operationName} is not implemented');
+  }
+`;
+}
+export {
+  generateMongoNativeService as default
+};