@specverse/engines 6.33.0 → 6.34.0

package/dist/realize/runtime-emitters/messaging.js

@@ -0,0 +1,423 @@
+/**
+ * Messaging-runtime emitter — V2 Phase 3, Round 2.
+ *
+ * Handles `topology: 'messaging'` factories: async pub/sub providers reached
+ * through external brokers (RabbitMQ, Kafka, NATS, AWS SQS).
+ *
+ * Conceptual difference from sync topologies (library / service / managed /
+ * executable):
+ *   - Sync topologies have a request/response contract: call op, get result.
+ *   - Messaging has a fire-and-forget contract: publish event, receive response
+ *     asynchronously or via subscription.
+ *
+ * For each `import:` entry the consumer declares, this emitter produces:
+ *   clients/<kebab-provider>.ts   — broker publish wrapper
+ *
+ * The publish wrapper:
+ *   - Reads `factory.v2metadata.protocol` to pick the SDK and init pattern:
+ *       amqp   → amqplib-based publisher with assertExchange + publish
+ *       kafka  → kafkajs producer
+ *       nats   → TODO stub (clear comment + right SDK shape)
+ *       sqs    → TODO stub (clear comment + right SDK shape)
+ *       other  → TODO stub (clear comment + right SDK shape)
+ *   - For each dotted op `Order.created`: emits a method that publishes the
+ *     message to the appropriate routing-key/topic/queue (`order.created`).
+ *   - Reads `factory.v2metadata.config?.exchange` / `config?.topic` /
+ *     `config?.queue` for routing config.
+ *   - Methods return `Promise<void>` (fire-and-forget).
+ *
+ * Connection lifecycle:
+ *   - Emits `init()` (call at app startup) and `shutdown()` (call at graceful
+ *     shutdown) on the client.
+ *   - Round 2 does NOT auto-wire these into the consumer's startup — that is a
+ *     Round 3 concern.
+ *
+ * No server-bind file:
+ *   - Messaging brokers are external services, not something the consumer hosts.
+ *   - Consumers PUBLISH to an existing broker; subscribe-side handlers come in
+ *     Round 3 via `subscribes_to:` blocks.
+ *
+ * Deployment instance hint:
+ *   - `result.notes` describes where the provider lands in the deployment spec:
+ *     `deployments.<env>.instances.communications.<provider>`.
+ *
+ * --- Select grammar ---
+ *
+ * `import.select` entries follow the same dotted grammar as library.ts:
+ *   - Dotted: `Order.created`  → publishes to routing-key `order.created`
+ *   - Bare:   `Events`         → stub method; routing-key inferred from name
+ *
+ * --- Round 2 limitations ---
+ *
+ * - Subscribe-side handlers (receiving events from the broker) are deferred to
+ *   Round 3; all `select:` entries are treated as publish-side by default.
+ * - NATS and SQS emit TODO stubs rather than real SDK code.
+ * - Config routing values (exchange, topic, queue) are read from
+ *   `factory.v2metadata` when present; absent values use reasonable defaults.
+ */
+// ─── Helpers shared with library.ts (inlined to keep emitters self-contained) ──
+/** Parse a select entry into head + optional tail (mirrors library.ts). */
+function parseSelectEntry(entry) {
+    const dotIndex = entry.indexOf('.');
+    if (dotIndex === -1) {
+        return { head: entry, tail: undefined };
+    }
+    return {
+        head: entry.slice(0, dotIndex),
+        tail: entry.slice(dotIndex + 1),
+    };
+}
+/** Normalise a `from:` name into an array of lowercase words. */
+function toWords(fromName) {
+    const normalised = fromName.replace(/^@/, '').replace(/\//g, '-');
+    return normalised
+        .replace(/([a-z])([A-Z])/g, '$1 $2')
+        .replace(/[^a-zA-Z0-9]+/g, ' ')
+        .trim()
+        .split(' ')
+        .filter(Boolean)
+        .map((w) => w.toLowerCase());
+}
+/** Convert a from-name to a lower-camelCase client constant prefix. */
+function toClientName(fromName) {
+    const words = toWords(fromName);
+    if (words.length === 0)
+        return 'unknownClient';
+    return (words[0] +
+        words
+            .slice(1)
+            .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+            .join(''));
+}
+/** Convert a from-name to PascalCase for type/interface names. */
+function toInterfaceName(fromName) {
+    const words = toWords(fromName);
+    return words.map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join('');
+}
+/** Convert a from-name to kebab-case for filenames. */
+function toFileName(fromName) {
+    return toWords(fromName).join('-');
+}
+// ─── Routing-key convention ───────────────────────────────────────────────────
+/**
+ * Derive a messaging routing-key / topic / queue name from an operation entry.
+ *
+ * Convention:
+ *   - Dotted `Order.created`  → `order.created`   (head.tail both lowercased)
+ *   - Bare   `Events`         → `events`           (just lowercased)
+ *
+ * This mirrors the natural AMQP / Kafka topic naming convention where dotted
+ * path segments separate domain entity from event name.
+ */
+function toRoutingKey(entry) {
+    const { head, tail } = parseSelectEntry(entry);
+    if (tail === undefined) {
+        return head.toLowerCase();
+    }
+    return `${head.toLowerCase()}.${tail.toLowerCase()}`;
+}
+/** Derive a safe TypeScript method name from a select entry. */
+function toMethodName(entry) {
+    const { head, tail } = parseSelectEntry(entry);
+    if (tail === undefined) {
+        // Bare entry: use head as camelCase
+        const w = toWords(head);
+        if (w.length === 0)
+            return 'publish';
+        return w[0] + w.slice(1).map((x) => x.charAt(0).toUpperCase() + x.slice(1)).join('');
+    }
+    // Dotted: combine head + tail → e.g. Order.created → orderCreated
+    const headWords = toWords(head);
+    const tailWords = toWords(tail);
+    const allWords = [...headWords, ...tailWords];
+    if (allWords.length === 0)
+        return 'publish';
+    return (allWords[0] +
+        allWords
+            .slice(1)
+            .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+            .join(''));
+}
+function extractRoutingConfig(factory) {
+    // factory.v2metadata?.config is free-form — cast via unknown
+    const cfg = factory.v2metadata?.['config'];
+    return {
+        exchange: typeof cfg?.['exchange'] === 'string' ? cfg['exchange'] : 'events',
+        topic: typeof cfg?.['topic'] === 'string' ? cfg['topic'] : null,
+        queue: typeof cfg?.['queue'] === 'string' ? cfg['queue'] : null,
+    };
+}
+// ─── amqp (RabbitMQ) ─────────────────────────────────────────────────────────
+function generateAmqpClient(interfaceName, clientName, selectEntries, routing) {
+    const exchange = routing.exchange;
+    const methods = buildPublishMethods(selectEntries, (entry, routingKey) => {
+        return [
+            `  async ${toMethodName(entry)}(payload: unknown): Promise<void> {`,
+            `    if (!this.channel) throw new Error('${clientName}: not initialised — call init() first');`,
+            `    await this.channel.assertExchange('${exchange}', 'topic', { durable: true });`,
+            `    this.channel.publish(`,
+            `      '${exchange}',`,
+            `      '${routingKey}',`,
+            `      Buffer.from(JSON.stringify(payload)),`,
+            `      { persistent: true },`,
+            `    );`,
+            `  }`,
+        ].join('\n');
+    });
+    return [
+        `import amqplib, { type Channel, type Connection } from 'amqplib';`,
+        ``,
+        `// FACTORY-EMITTED — DO NOT EDIT (R8)`,
+        `// Generated by messaging-runtime emitter — V2 Phase 3, Round 2`,
+        `// Protocol: amqp (RabbitMQ via amqplib)`,
+        ``,
+        `export type ${interfaceName}Client = {`,
+        `  init(): Promise<void>;`,
+        `  shutdown(): Promise<void>;`,
+        ...selectEntries
+            .filter((v, i, a) => a.indexOf(v) === i)
+            .map((entry) => {
+            const methodName = toMethodName(entry);
+            return `  ${methodName}(payload: unknown): Promise<void>;`;
+        }),
+        `};`,
+        ``,
+        `class ${interfaceName}Publisher implements ${interfaceName}Client {`,
+        `  private connection: Connection | null = null;`,
+        `  private channel: Channel | null = null;`,
+        ``,
+        `  constructor(private readonly brokerUrl: string) {}`,
+        ``,
+        `  async init(): Promise<void> {`,
+        `    this.connection = await amqplib.connect(this.brokerUrl);`,
+        `    this.channel = await this.connection.createConfirmChannel();`,
+        `  }`,
+        ``,
+        `  async shutdown(): Promise<void> {`,
+        `    await this.channel?.close();`,
+        `    await this.connection?.close();`,
+        `    this.channel = null;`,
+        `    this.connection = null;`,
+        `  }`,
+        ``,
+        ...methods,
+        `}`,
+        ``,
+        `const brokerUrl = process.env['AMQP_URL'] ?? 'amqp://localhost';`,
+        `export const ${clientName}Client: ${interfaceName}Client = new ${interfaceName}Publisher(brokerUrl);`,
+        ``,
+    ].join('\n');
+}
+// ─── kafka ────────────────────────────────────────────────────────────────────
+function generateKafkaClient(interfaceName, clientName, selectEntries, routing) {
+    const methods = buildPublishMethods(selectEntries, (entry, routingKey) => {
+        const topic = routing.topic ?? routingKey;
+        return [
+            `  async ${toMethodName(entry)}(payload: unknown): Promise<void> {`,
+            `    await this.producer.send({`,
+            `      topic: '${topic}',`,
+            `      messages: [{ value: JSON.stringify(payload) }],`,
+            `    });`,
+            `  }`,
+        ].join('\n');
+    });
+    return [
+        `import { Kafka, type Producer } from 'kafkajs';`,
+        ``,
+        `// FACTORY-EMITTED — DO NOT EDIT (R8)`,
+        `// Generated by messaging-runtime emitter — V2 Phase 3, Round 2`,
+        `// Protocol: kafka (Apache Kafka via kafkajs)`,
+        ``,
+        `export type ${interfaceName}Client = {`,
+        `  init(): Promise<void>;`,
+        `  shutdown(): Promise<void>;`,
+        ...selectEntries
+            .filter((v, i, a) => a.indexOf(v) === i)
+            .map((entry) => {
+            const methodName = toMethodName(entry);
+            return `  ${methodName}(payload: unknown): Promise<void>;`;
+        }),
+        `};`,
+        ``,
+        `class ${interfaceName}Producer implements ${interfaceName}Client {`,
+        `  private producer: Producer;`,
+        ``,
+        `  constructor(brokers: string[]) {`,
+        `    const kafka = new Kafka({`,
+        `      clientId: '${clientName}',`,
+        `      brokers,`,
+        `    });`,
+        `    this.producer = kafka.producer();`,
+        `  }`,
+        ``,
+        `  async init(): Promise<void> {`,
+        `    await this.producer.connect();`,
+        `  }`,
+        ``,
+        `  async shutdown(): Promise<void> {`,
+        `    await this.producer.disconnect();`,
+        `  }`,
+        ``,
+        ...methods,
+        `}`,
+        ``,
+        `const brokers = (process.env['KAFKA_BROKERS'] ?? 'localhost:9092').split(',');`,
+        `export const ${clientName}Client: ${interfaceName}Client = new ${interfaceName}Producer(brokers);`,
+        ``,
+    ].join('\n');
+}
+// ─── TODO stub (nats / sqs / unknown) ────────────────────────────────────────
+function generateTodoStubClient(interfaceName, clientName, selectEntries, protocol) {
+    const sdkHint = protocol === 'nats' ? 'nats.ws / nats.js' : protocol === 'sqs' ? '@aws-sdk/client-sqs' : `SDK for protocol '${protocol}'`;
+    return [
+        `// FACTORY-EMITTED — DO NOT EDIT (R8)`,
+        `// Generated by messaging-runtime emitter — V2 Phase 3, Round 2`,
+        `// Protocol: ${protocol} — TODO: install ${sdkHint} and implement`,
+        ``,
+        `export type ${interfaceName}Client = {`,
+        `  init(): Promise<void>;`,
+        `  shutdown(): Promise<void>;`,
+        ...selectEntries
+            .filter((v, i, a) => a.indexOf(v) === i)
+            .map((entry) => {
+            const methodName = toMethodName(entry);
+            return `  ${methodName}(payload: unknown): Promise<void>;`;
+        }),
+        `};`,
+        ``,
+        `// TODO (Round 3): implement ${protocol.toUpperCase()} publisher using ${sdkHint}.`,
+        `// Methods below throw at runtime to surface missing wiring clearly.`,
+        `export const ${clientName}Client: ${interfaceName}Client = {`,
+        `  async init(): Promise<void> {`,
+        `    throw new Error('${clientName}: ${protocol} publisher not yet implemented — Round 3 TODO');`,
+        `  },`,
+        `  async shutdown(): Promise<void> {`,
+        `    // no-op until implemented`,
+        `  },`,
+        ...selectEntries
+            .filter((v, i, a) => a.indexOf(v) === i)
+            .map((entry) => {
+            const methodName = toMethodName(entry);
+            return [
+                `  async ${methodName}(_payload: unknown): Promise<void> {`,
+                `    throw new Error('${methodName} (${clientName}): ${protocol} publisher not yet implemented — Round 3 TODO');`,
+                `  },`,
+            ].join('\n');
+        }),
+        `};`,
+        ``,
+    ].join('\n');
+}
+// ─── Shared helper: build publish method bodies ───────────────────────────────
+/**
+ * Build deduplicated publish method bodies for a set of select entries.
+ * Returns an array of method strings (no trailing blank lines between them —
+ * caller joins the sections).
+ */
+function buildPublishMethods(selectEntries, methodBody) {
+    const seen = new Set();
+    const parts = [];
+    for (const entry of selectEntries) {
+        if (seen.has(entry))
+            continue;
+        seen.add(entry);
+        const routingKey = toRoutingKey(entry);
+        parts.push(methodBody(entry, routingKey));
+        parts.push('');
+    }
+    return parts;
+}
+// ─── Messaging emitter ────────────────────────────────────────────────────────
+/**
+ * Messaging-runtime emitter implementation.
+ *
+ * One call to `emit()` processes a single `import:` entry and produces
+ * one client file under `clients/<provider-filename>.ts`.
+ *
+ * The client file contains:
+ *   - A typed `<Provider>Client` interface with all selected operations as
+ *     `(payload: unknown) => Promise<void>` methods, plus `init()` / `shutdown()`.
+ *   - A protocol-specific implementation class (amqp / kafka) or a TODO stub.
+ *   - An exported singleton constant `<provider>Client` for the consumer to import.
+ *
+ * No server-bind file is emitted — the broker is an external service.
+ */
+export class MessagingRuntimeEmitter {
+    topology = 'messaging';
+    async emit(ctx) {
+        const { importEntry, factory, outputDir } = ctx;
+        const selectEntries = importEntry.select ?? [];
+        // Derive naming from the import's `from:` field, not the factory name.
+        const fileName = toFileName(importEntry.from);
+        const clientName = toClientName(importEntry.from);
+        const interfaceName = toInterfaceName(importEntry.from);
+        // File path relative to outputDir.
+        const relFilePath = `clients/${fileName}.ts`;
+        // Detect the protocol from factory v2metadata.
+        const protocol = factory.v2metadata?.protocol ?? 'unknown';
+        const routing = extractRoutingConfig(factory);
+        // Generate the content based on the protocol.
+        let content;
+        switch (protocol) {
+            case 'amqp':
+                content = generateAmqpClient(interfaceName, clientName, selectEntries, routing);
+                break;
+            case 'kafka':
+                content = generateKafkaClient(interfaceName, clientName, selectEntries, routing);
+                break;
+            case 'nats':
+            case 'sqs':
+            default:
+                content = generateTodoStubClient(interfaceName, clientName, selectEntries, protocol);
+                break;
+        }
+        // Build the import entry for the consumer's controller file.
+        const consumerImport = {
+            from: `./clients/${fileName}`,
+            specifier: `${clientName}Client`,
+        };
+        // Warnings + notes.
+        const notes = [];
+        // Always emit the deployment instance hint.
+        notes.push(`Deployment instance hint: add provider under deployments.<env>.instances.communications.${clientName}` +
+            ` with config: { broker: '<url>'` +
+            (routing.exchange !== 'events' ? `, exchange: '${routing.exchange}'` : '') +
+            (routing.topic ? `, topic: '${routing.topic}'` : '') +
+            (routing.queue ? `, queue: '${routing.queue}'` : '') +
+            ` }.`);
+        if (selectEntries.length === 0) {
+            notes.push(`Warning: import entry from '${importEntry.from}' has empty select: — no publish methods emitted.`);
+        }
+        if (protocol !== 'amqp' && protocol !== 'kafka') {
+            notes.push(`TODO (Round 3): protocol '${protocol}' emits a stub — implement the publisher using the appropriate SDK.`);
+        }
+        const config = { broker: '<url>', protocol };
+        if (routing.exchange && routing.exchange !== 'events')
+            config.exchange = routing.exchange;
+        if (routing.topic)
+            config.topic = routing.topic;
+        if (routing.queue)
+            config.queue = routing.queue;
+        const reviewNotes = [];
+        if (protocol !== 'amqp' && protocol !== 'kafka') {
+            reviewNotes.push(`Protocol '${protocol}' emits a stub — implement the publisher using the appropriate SDK.`);
+        }
+        const deploymentSuggestion = {
+            provider: importEntry.from,
+            consumerComponent: ctx.consumerComponent?.name,
+            category: 'communications',
+            key: clientName,
+            config,
+            factory: factory.name,
+            topology: 'messaging',
+            ...(reviewNotes.length > 0 ? { reviewNotes } : {}),
+        };
+        return {
+            files: [{ path: relFilePath, content }],
+            imports: [consumerImport],
+            notes,
+            deploymentSuggestion,
+        };
+    }
+}
+//# sourceMappingURL=messaging.js.map

package/dist/realize/runtime-emitters/messaging.js.map

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

package/dist/realize/runtime-emitters/service.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Service-runtime emitter — V2 Phase 3, Round 2.
+ *
+ * Handles `topology: 'service'` factories: providers that ship as
+ * network-attached services we deploy ourselves (REST / gRPC / MCP).
+ *
+ * For each `import:` entry the consumer declares, this emitter produces:
+ *   clients/<provider-name>.ts                — typed network client
+ *   servers/<provider-name>-server.ts (cond.) — Fastify route scaffold
+ *
+ * The server-bind file is emitted only when `factory.v2metadata?.serverTemplate`
+ * is non-null and non-empty. Managed/external providers (we don't host them)
+ * leave it null; we-host providers populate it.
+ *
+ * Protocol dispatch (factory.v2metadata?.protocol):
+ *   'rest' (default)   → fetch-based HTTP client; one POST per dotted op
+ *   'grpc'             → gRPC stub init (Round 2: TODO scaffolding)
+ *   'mcp'              → MCP client init (Round 2: TODO scaffolding)
+ *
+ * Endpoint env-var resolution:
+ *   1. factory.v2metadata?.config?.endpoint?.env if present
+ *   2. Convention <UPPERCASE_PROVIDER>_API_URL otherwise
+ *
+ * Deployment hint: realize emits a `deployments.<env>.instances.services.<provider>`
+ * entry with `config: { endpoint: { env: <ENV_NAME> } }` — mentioned in result.notes
+ * for the consumer's review. The actual instance emission is upstream of this
+ * emitter; here we just declare the convention.
+ */
+import type { RuntimeEmitter, RuntimeEmitterContext, RuntimeEmitterResult } from './dispatcher.js';
+/**
+ * Service-runtime emitter implementation.
+ *
+ * One call to `emit()` processes a single `import:` entry. Produces:
+ *   - 1 client file under `clients/<provider-filename>.ts`
+ *   - 1 server-bind file under `servers/<provider-filename>-server.ts` (only
+ *     when factory.v2metadata.serverTemplate is non-null)
+ */
+export declare class ServiceRuntimeEmitter implements RuntimeEmitter {
+    readonly topology: "service";
+    emit(ctx: RuntimeEmitterContext): Promise<RuntimeEmitterResult>;
+}
+//# sourceMappingURL=service.d.ts.map

package/dist/realize/runtime-emitters/service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../../../src/realize/runtime-emitters/service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,KAAK,EACV,cAAc,EACd,qBAAqB,EACrB,oBAAoB,EACrB,MAAM,iBAAiB,CAAC;AAmSzB;;;;;;;GAOG;AACH,qBAAa,qBAAsB,YAAW,cAAc;IAC1D,QAAQ,CAAC,QAAQ,EAAG,SAAS,CAAU;IAEjC,IAAI,CAAC,GAAG,EAAE,qBAAqB,GAAG,OAAO,CAAC,oBAAoB,CAAC;CAkFtE"}