@specverse/engines 6.33.0 → 6.34.0

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

@@ -0,0 +1,283 @@
+/**
+ * Managed-runtime emitter — V2 Phase 3, Round 2.
+ *
+ * Handles `topology: 'managed'` factories: external SaaS providers reached
+ * via vendor-specific SDKs (Stripe, OpenAI, Anthropic, Twilio, AWS, etc.).
+ *
+ * For each `import:` entry the consumer declares, this emitter produces:
+ *   clients/<provider-name>.ts   — SDK init + typed client
+ *
+ * No server-bind file — managed providers ship their own server.
+ *
+ * Auth dispatch (factory.v2metadata?.authentication?.kind):
+ *   'api-key'  → `new SDK(process.env.<ENV>!)` constructor pattern (Stripe-shape)
+ *   'bearer'   → header-based init reading token from env
+ *   'oauth2'   → TODO scaffolding; init throws at call-time (Round 3)
+ *   'mtls'     → env-driven cert paths
+ *   'none'     → bare SDK init, no auth wiring
+ *
+ * Env var name: factory.v2metadata?.authentication?.env if present, else
+ * derived from provider (STRIPE_API_KEY, OPENAI_API_KEY, etc.). Suffix
+ * varies by auth.kind (_API_KEY / _TOKEN / _BEARER / _CERT).
+ *
+ * Operation routing: dotted ops like `Charge.create` route to
+ * `sdk.charges.create(...)` — entity head is lowercased + naively
+ * pluralised; tail becomes the SDK method. Exact mapping varies per
+ * SDK; Round 3 enhancement allows spec authors to override.
+ *
+ * Deployment hint: realize emits a `deployments.<env>.instances.infrastructure.<provider>`
+ * entry with `config: { provider: <hostname>, authEnv: <ENV_NAME> }` —
+ * mentioned in result.notes.
+ */
+// ─── Naming helpers (shared shape with 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) };
+}
+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());
+}
+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(''));
+}
+function toInterfaceName(fromName) {
+    return toWords(fromName)
+        .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+        .join('');
+}
+function toFileName(fromName) {
+    return toWords(fromName).join('-');
+}
+function resolveAuth(ctx) {
+    const auth = ctx.factory.v2metadata?.authentication;
+    const kind = auth?.kind ?? 'api-key';
+    const upperProvider = toWords(ctx.importEntry.from).join('_').toUpperCase();
+    let envVar;
+    if (auth?.env && typeof auth.env === 'string') {
+        envVar = auth.env;
+    }
+    else {
+        const suffix = kind === 'bearer' ? '_TOKEN'
+            : kind === 'oauth2' ? '_CLIENT_SECRET'
+                : kind === 'mtls' ? '_CERT'
+                    : kind === 'none' ? ''
+                        : '_API_KEY';
+        envVar = upperProvider + suffix;
+    }
+    return {
+        kind,
+        envVar,
+        certEnvVar: auth?.certEnv,
+        keyEnvVar: auth?.keyEnv,
+    };
+}
+function resolveSdkSpecifier(ctx) {
+    const sdk = ctx.factory.v2metadata?.sdk;
+    return sdk ?? ctx.importEntry.from;
+}
+/**
+ * Naive pluralise — appends `s` unless the word already ends in `s`.
+ * SDK method conventions vary (charges, customers, invoices); spec authors
+ * who need a different mapping can override per-call. Round 3 enhancement.
+ */
+function pluraliseLower(name) {
+    const lower = name.toLowerCase();
+    return lower.endsWith('s') ? lower : `${lower}s`;
+}
+// ─── Auth init pattern generators ─────────────────────────────────────────────
+function generateAuthInit(sdkSpecifier, sdkVarName, auth) {
+    const lines = [];
+    switch (auth.kind) {
+        case 'api-key':
+            lines.push(`import SDK from '${sdkSpecifier}';`);
+            lines.push('');
+            lines.push(`const apiKey = process.env.${auth.envVar};`);
+            lines.push(`if (!apiKey) throw new Error('${auth.envVar} env var is not set; required for ${sdkSpecifier} client');`);
+            lines.push(`const ${sdkVarName} = new SDK(apiKey);`);
+            break;
+        case 'bearer':
+            lines.push(`import SDK from '${sdkSpecifier}';`);
+            lines.push('');
+            lines.push(`const bearerToken = process.env.${auth.envVar};`);
+            lines.push(`if (!bearerToken) throw new Error('${auth.envVar} env var is not set; required for ${sdkSpecifier} client');`);
+            lines.push(`const ${sdkVarName} = new SDK({`);
+            lines.push(`  headers: { Authorization: \`Bearer \${bearerToken}\` },`);
+            lines.push(`});`);
+            break;
+        case 'oauth2':
+            lines.push(`import SDK from '${sdkSpecifier}';`);
+            lines.push('');
+            lines.push(`// TODO (Round 3): wire OAuth2 client-credentials / authorization-code flow.`);
+            lines.push(`//   Round 2 leaves this as a clear scaffolding stub. Configure the client_id`);
+            lines.push(`//   and client_secret env vars + token endpoint, then exchange for a bearer token.`);
+            lines.push(`function init${sdkVarName.charAt(0).toUpperCase() + sdkVarName.slice(1)}(): never {`);
+            lines.push(`  throw new Error('OAuth2 wiring is a Round 3 TODO for ${sdkSpecifier} — supply token-exchange logic.');`);
+            lines.push(`}`);
+            lines.push(`const ${sdkVarName}: ReturnType<typeof init${sdkVarName.charAt(0).toUpperCase() + sdkVarName.slice(1)}> = init${sdkVarName.charAt(0).toUpperCase() + sdkVarName.slice(1)}();`);
+            break;
+        case 'mtls':
+            lines.push(`import SDK from '${sdkSpecifier}';`);
+            lines.push(`import { readFileSync } from 'node:fs';`);
+            lines.push('');
+            lines.push(`const certPath = process.env.${auth.certEnvVar ?? auth.envVar};`);
+            lines.push(`const keyPath = process.env.${auth.keyEnvVar ?? auth.envVar.replace(/_CERT$/, '_KEY')};`);
+            lines.push(`if (!certPath || !keyPath) throw new Error('mTLS cert/key env vars not set; required for ${sdkSpecifier} client');`);
+            lines.push(`const ${sdkVarName} = new SDK({`);
+            lines.push(`  cert: readFileSync(certPath),`);
+            lines.push(`  key: readFileSync(keyPath),`);
+            lines.push(`});`);
+            break;
+        case 'none':
+            lines.push(`import SDK from '${sdkSpecifier}';`);
+            lines.push('');
+            lines.push(`const ${sdkVarName} = new SDK();`);
+            break;
+    }
+    return lines;
+}
+// ─── Interface + constant generators ──────────────────────────────────────────
+function generateInterface(interfaceName, selectEntries) {
+    const lines = [];
+    lines.push(`export type ${interfaceName}Client = {`);
+    const seen = new Set();
+    for (const entry of selectEntries) {
+        if (seen.has(entry))
+            continue;
+        seen.add(entry);
+        const { head, tail } = parseSelectEntry(entry);
+        if (tail === undefined) {
+            lines.push(`  /** ${head} entity — passthrough to SDK. Round 3: substitute real type. */`);
+            lines.push(`  ${head}(...args: unknown[]): Promise<unknown>;`);
+        }
+        else {
+            lines.push(`  /** ${head}.${tail} → sdk.${pluraliseLower(head)}.${tail}. Round 3: substitute real input/output types. */`);
+            lines.push(`  ${tail}(input: unknown): Promise<unknown>;`);
+        }
+    }
+    lines.push('};');
+    return lines.join('\n');
+}
+function generateClientConstant(clientName, interfaceName, sdkVarName, selectEntries, auth) {
+    const lines = [];
+    lines.push(`export const ${clientName}Client: ${interfaceName}Client = {`);
+    const seen = new Set();
+    for (const entry of selectEntries) {
+        if (seen.has(entry))
+            continue;
+        seen.add(entry);
+        const { head, tail } = parseSelectEntry(entry);
+        if (tail === undefined) {
+            // Bare entity — passthrough to a top-level SDK property of that name.
+            lines.push(`  ${head}(...args: unknown[]): Promise<unknown> {`);
+            if (auth.kind === 'oauth2') {
+                lines.push(`    throw new Error('${head}: OAuth2 wiring is a Round 3 TODO');`);
+            }
+            else {
+                lines.push(`    return Promise.resolve(((${sdkVarName} as unknown) as Record<string, (...a: unknown[]) => unknown>)['${head}']?.(...args));`);
+            }
+            lines.push(`  },`);
+        }
+        else {
+            // Dotted op — route to sdk.<plural-head>.<tail>.
+            const sdkProp = pluraliseLower(head);
+            lines.push(`  ${tail}(input: unknown): Promise<unknown> {`);
+            if (auth.kind === 'oauth2') {
+                lines.push(`    throw new Error('${head}.${tail}: OAuth2 wiring is a Round 3 TODO');`);
+            }
+            else {
+                lines.push(`    const sdkAny = (${sdkVarName} as unknown) as Record<string, Record<string, (input: unknown) => Promise<unknown>>>;`);
+                lines.push(`    const fn = sdkAny['${sdkProp}']?.['${tail}'];`);
+                lines.push(`    if (typeof fn !== 'function') throw new Error('${sdkProp}.${tail} not found on SDK; check the SDK shape or override the mapping in the spec.');`);
+                lines.push(`    return fn(input);`);
+            }
+            lines.push(`  },`);
+        }
+    }
+    lines.push('};');
+    return lines.join('\n');
+}
+// ─── Managed emitter ──────────────────────────────────────────────────────────
+/**
+ * Managed-runtime emitter implementation.
+ *
+ * One call to `emit()` processes a single `import:` entry. Produces:
+ *   - 1 client file under `clients/<provider-filename>.ts`
+ *   - NO server-bind file (managed providers ship their own server).
+ */
+export class ManagedRuntimeEmitter {
+    topology = 'managed';
+    async emit(ctx) {
+        const { importEntry, factory } = ctx;
+        const selectEntries = importEntry.select ?? [];
+        const fileName = toFileName(importEntry.from);
+        const clientName = toClientName(importEntry.from);
+        const interfaceName = toInterfaceName(importEntry.from);
+        const sdkSpecifier = resolveSdkSpecifier(ctx);
+        const sdkVarName = `${clientName}Sdk`;
+        const auth = resolveAuth(ctx);
+        // Build header.
+        const headerLines = [
+            '// FACTORY-EMITTED — DO NOT EDIT (R8)',
+            `// Generated by managed-runtime emitter — V2 Phase 3`,
+            `// Provider: ${importEntry.from} (managed SaaS via factory: ${factory.name})`,
+            `// SDK: ${sdkSpecifier}`,
+            `// Authentication: ${auth.kind} (env: ${auth.envVar})`,
+            '',
+        ];
+        const initLines = generateAuthInit(sdkSpecifier, sdkVarName, auth);
+        const interfaceBlock = generateInterface(interfaceName, selectEntries);
+        const constantBlock = generateClientConstant(clientName, interfaceName, sdkVarName, selectEntries, auth);
+        const parts = [...headerLines, ...initLines, '', interfaceBlock, '', constantBlock, ''];
+        const content = parts.join('\n');
+        const consumerImport = {
+            from: `./clients/${fileName}`,
+            specifier: `${clientName}Client`,
+        };
+        const notes = [
+            `Deployment hint: deployments.<env>.instances.infrastructure.${clientName} with config: { provider: '${importEntry.from}', authEnv: '${auth.envVar}' } (factory: ${factory.name}, auth: ${auth.kind}).`,
+        ];
+        if (selectEntries.length === 0) {
+            notes.push(`Warning: import entry from '${importEntry.from}' has empty select: — no client members emitted.`);
+        }
+        if (auth.kind === 'oauth2') {
+            notes.push(`TODO (Round 3): OAuth2 flow for ${importEntry.from} — supply token-exchange logic. Methods throw at call-time until wired.`);
+        }
+        const reviewNotes = [];
+        if (auth.kind === 'oauth2') {
+            reviewNotes.push(`OAuth2 flow for ${importEntry.from} — supply token-exchange logic; methods throw at call-time until wired.`);
+        }
+        const deploymentSuggestion = {
+            provider: importEntry.from,
+            consumerComponent: ctx.consumerComponent?.name,
+            category: 'infrastructure',
+            key: clientName,
+            config: {
+                provider: importEntry.from,
+                authEnv: auth.envVar,
+            },
+            factory: factory.name,
+            topology: 'managed',
+            ...(reviewNotes.length > 0 ? { reviewNotes } : {}),
+        };
+        return {
+            files: [{ path: `clients/${fileName}.ts`, content }],
+            imports: [consumerImport],
+            notes,
+            deploymentSuggestion,
+        };
+    }
+}
+//# sourceMappingURL=managed.js.map

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

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

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

@@ -0,0 +1,77 @@
+/**
+ * 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.
+ */
+import type { RuntimeEmitter, RuntimeEmitterContext, RuntimeEmitterResult } from './dispatcher.js';
+/**
+ * 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 declare class MessagingRuntimeEmitter implements RuntimeEmitter {
+    readonly topology: "messaging";
+    emit(ctx: RuntimeEmitterContext): Promise<RuntimeEmitterResult>;
+}
+//# sourceMappingURL=messaging.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"messaging.d.ts","sourceRoot":"","sources":["../../../src/realize/runtime-emitters/messaging.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AAEH,OAAO,KAAK,EACV,cAAc,EACd,qBAAqB,EACrB,oBAAoB,EACrB,MAAM,iBAAiB,CAAC;AAyUzB;;;;;;;;;;;;;GAaG;AACH,qBAAa,uBAAwB,YAAW,cAAc;IAC5D,QAAQ,CAAC,QAAQ,EAAG,WAAW,CAAU;IAEnC,IAAI,CAAC,GAAG,EAAE,qBAAqB,GAAG,OAAO,CAAC,oBAAoB,CAAC;CA2FtE"}