@idevconn/create-icore 0.4.0 → 0.5.0

package/templates/libs/jobs-client/src/lib/jobs-client.service.ts

@@ -2,7 +2,7 @@ import { Inject, Injectable, OnModuleDestroy } from '@nestjs/common';
 import { Queue, type JobsOptions } from 'bullmq';
 import IORedis from 'ioredis';
 import { ICORE_QUEUES, type JobsMap } from '@icore/shared';
-import { JOBS_REDIS_URL } from './jobs-client.module';
+import { JOBS_REDIS_URL } from './jobs-client.tokens';
 
 @Injectable()
 export class JobsClientService implements OnModuleDestroy {

package/templates/libs/jobs-client/src/lib/jobs-client.tokens.ts

@@ -0,0 +1,4 @@
+// Injection token — kept in its own file so module and service can both
+// import it without creating a circular dependency (which breaks DI in
+// webpack-bundled NestJS apps).
+export const JOBS_REDIS_URL = 'JOBS_REDIS_URL';

package/templates/libs/notes-client/src/index.ts

@@ -1,2 +1,3 @@
+export * from './lib/notes-client.tokens';
 export * from './lib/notes-client.module';
 export * from './lib/notes-client.service';

package/templates/libs/notes-client/src/lib/notes-client.module.ts

@@ -3,7 +3,7 @@ import { ClientsModule } from '@nestjs/microservices';
 import { buildTransport } from '@icore/shared';
 import { NotesClientService } from './notes-client.service';
 
-export const NOTES_CLIENT = 'NOTES_CLIENT';
+import { NOTES_CLIENT } from './notes-client.tokens';
 
 @Module({})
 export class NotesClientModule {

package/templates/libs/notes-client/src/lib/notes-client.service.ts

@@ -2,7 +2,7 @@ import { Inject, Injectable } from '@nestjs/common';
 import { ClientProxy } from '@nestjs/microservices';
 import { firstValueFrom } from 'rxjs';
 import type { ListNotesOptions, Note } from '@icore/shared';
-import { NOTES_CLIENT } from './notes-client.module';
+import { NOTES_CLIENT } from './notes-client.tokens';
 
 @Injectable()
 export class NotesClientService {

package/templates/libs/notes-client/src/lib/notes-client.tokens.ts

@@ -0,0 +1,4 @@
+// Injection token — kept in its own file so module and service can both
+// import it without creating a circular dependency (which breaks DI in
+// webpack-bundled NestJS apps).
+export const NOTES_CLIENT = 'NOTES_CLIENT';

package/templates/libs/payment-client/src/index.ts

@@ -1,2 +1,3 @@
+export * from './lib/payment-client.tokens';
 export * from './lib/payment-client.module';
 export * from './lib/payment-client.service';

package/templates/libs/payment-client/src/lib/payment-client.module.ts

@@ -3,7 +3,7 @@ import { ClientsModule } from '@nestjs/microservices';
 import { buildTransport } from '@icore/shared';
 import { PaymentClientService } from './payment-client.service';
 
-export const PAYMENT_CLIENT = 'PAYMENT_CLIENT';
+import { PAYMENT_CLIENT } from './payment-client.tokens';
 
 @Module({})
 export class PaymentClientModule {

package/templates/libs/payment-client/src/lib/payment-client.service.ts

@@ -7,7 +7,7 @@ import type {
   OrderResult,
   RequestOptions,
 } from '@idevconn/payment';
-import { PAYMENT_CLIENT } from './payment-client.module';
+import { PAYMENT_CLIENT } from './payment-client.tokens';
 
 @Injectable()
 export class PaymentClientService {

package/templates/libs/payment-client/src/lib/payment-client.tokens.ts

@@ -0,0 +1,4 @@
+// Injection token — kept in its own file so module and service can both
+// import it without creating a circular dependency (which breaks DI in
+// webpack-bundled NestJS apps).
+export const PAYMENT_CLIENT = 'PAYMENT_CLIENT';

package/templates/libs/shared/src/env.ts

@@ -0,0 +1,88 @@
+// Server-side env helpers. NOT exported from ./client (browser-safe entry) —
+// generated microservices import these to report which provider credentials
+// are missing on startup instead of crashing.
+
+/**
+ * Returns the keys whose value is missing or blank.
+ * @param get   accessor (e.g. ConfigService.get bound to the MS config)
+ * @param keys  env var names required for the selected provider
+ */
+export function missingEnv(get: (key: string) => string | undefined, keys: string[]): string[] {
+  return keys.filter((k) => !get(k)?.trim());
+}
+
+/**
+ * Builds an eye-catching boxed banner listing the env vars a microservice
+ * needs but is missing, so it stands out in the `yarn dev` log noise.
+ */
+export function formatEnvBanner(opts: {
+  service: string;
+  provider: string | undefined;
+  missing: string[];
+  envPath: string;
+  reason?: string;
+  /** Override the first line. Defaults to the in-memory-fake warning. */
+  headline?: string;
+}): string {
+  const { service, provider, missing, envPath, reason, headline } = opts;
+  const lines: string[] = [];
+  lines.push(headline ?? `⚠  ${service} — running with an IN-MEMORY FAKE (requests will fail)`);
+  lines.push('');
+  if (!provider) {
+    lines.push(`Provider env var is not set.`);
+  } else if (missing.length > 0) {
+    lines.push(`"${provider}" needs these env vars, currently missing:`);
+    for (const k of missing) lines.push(`  • ${k}`);
+  } else if (reason) {
+    // Vars are present but invalid (e.g. placeholder URL the SDK rejected).
+    lines.push(`"${provider}" failed to initialise:`);
+    lines.push(`  ${reason}`);
+  }
+  lines.push('');
+  lines.push(`Set real values in:  ${envPath}`);
+
+  const width = Math.max(...lines.map((l) => l.length), 50);
+  const top = `╔═${'═'.repeat(width)}═╗`;
+  const bot = `╚═${'═'.repeat(width)}═╝`;
+  const body = lines.map((l) => `║ ${l.padEnd(width)} ║`).join('\n');
+  return `\n${top}\n${body}\n${bot}`;
+}
+
+/**
+ * Returns a boxed startup info banner listing every MS the gateway will
+ * connect to, reading the current transport env vars.
+ */
+export function formatGatewayBanner(opts: {
+  port: number;
+  origin: string;
+  services: Array<{ name: string; prefix: string }>;
+}): string {
+  const { port, origin, services } = opts;
+  const lines: string[] = [];
+  lines.push(`Gateway listening on  ${origin}:${port}/api`);
+  lines.push(`Swagger UI            ${origin}:${port}/api/docs`);
+  lines.push('');
+  lines.push('Microservice transports:');
+  for (const { name, prefix } of services) {
+    const kind = (process.env[`${prefix}_TRANSPORT`] ?? 'tcp').toLowerCase();
+    let target: string;
+    if (kind === 'tcp') {
+      const host = process.env[`${prefix}_HOST`] ?? '127.0.0.1';
+      const port_ = process.env[`${prefix}_PORT`] ?? '?';
+      target = `tcp  ${host}:${port_}`;
+    } else if (kind === 'redis') {
+      target = `redis  ${process.env[`${prefix}_REDIS_URL`] ?? '(REDIS_URL not set)'}`;
+    } else if (kind === 'nats') {
+      target = `nats  ${process.env[`${prefix}_NATS_URL`] ?? '(NATS_URL not set)'}`;
+    } else {
+      target = kind;
+    }
+    lines.push(`  ${name.padEnd(10)} →  ${target}`);
+  }
+
+  const width = Math.max(...lines.map((l) => l.length), 50);
+  const top = `╔═${'═'.repeat(width)}═╗`;
+  const bot = `╚═${'═'.repeat(width)}═╝`;
+  const body = lines.map((l) => `║ ${l.padEnd(width)} ║`).join('\n');
+  return `\n${top}\n${body}\n${bot}`;
+}

package/templates/libs/shared/src/index.ts

@@ -1,3 +1,4 @@
+export * from './env';
 export * from './abilities';
 export * from './jobs';
 export * from './strategies';

package/templates/libs/shared/src/transport.ts

@@ -1,4 +1,40 @@
 import { Transport, type ClientOptions, type MicroserviceOptions } from '@nestjs/microservices';
+import { formatEnvBanner } from './env';
+
+// Transport vars each kind needs (besides ${prefix}_TRANSPORT itself).
+function transportKeys(prefix: string, kind: string): string[] {
+  switch (kind) {
+    case 'tcp':
+      return [`${prefix}_HOST`, `${prefix}_PORT`];
+    case 'redis':
+      return [`${prefix}_REDIS_URL`];
+    case 'nats':
+      return [`${prefix}_NATS_URL`];
+    default:
+      return [];
+  }
+}
+
+/**
+ * Throws an eye-catching banner if any transport var for `prefix` is missing.
+ * Used by both the gateway client modules and each MS bootstrap, so transport
+ * misconfiguration surfaces clearly instead of a raw "Missing env var".
+ */
+function assertTransportEnv(prefix: string, kind: string): void {
+  const keys = transportKeys(prefix, kind);
+  const missing = keys.filter((k) => !process.env[k]?.trim());
+  if (missing.length > 0) {
+    throw new Error(
+      formatEnvBanner({
+        service: `${prefix} transport`,
+        provider: kind,
+        missing,
+        envPath: `the service .env (${prefix}_* transport vars)`,
+        headline: `⚠  ${prefix} transport (${kind}) not configured — cannot reach the microservice`,
+      }),
+    );
+  }
+}
 
 function required(name: string): string {
   const value = process.env[name];
@@ -17,6 +53,7 @@ function requiredPort(name: string): number {
 
 export function buildTransport(prefix: string): ClientOptions {
   const kind = (process.env[`${prefix}_TRANSPORT`] ?? 'tcp').toLowerCase();
+  assertTransportEnv(prefix, kind);
   switch (kind) {
     case 'tcp':
       return {

package/templates/libs/upload-client/src/index.ts

@@ -1,2 +1,3 @@
+export * from './lib/upload-client.tokens';
 export * from './lib/upload-client.module';
 export * from './lib/upload-client.service';

package/templates/libs/upload-client/src/lib/upload-client.module.ts

@@ -3,7 +3,7 @@ import { ClientsModule } from '@nestjs/microservices';
 import { buildTransport } from '@icore/shared';
 import { UploadClientService } from './upload-client.service';
 
-export const UPLOAD_CLIENT = 'UPLOAD_CLIENT';
+import { UPLOAD_CLIENT } from './upload-client.tokens';
 
 @Module({})
 export class UploadClientModule {

package/templates/libs/upload-client/src/lib/upload-client.service.ts

@@ -2,7 +2,7 @@ import { Inject, Injectable } from '@nestjs/common';
 import { ClientProxy } from '@nestjs/microservices';
 import { firstValueFrom } from 'rxjs';
 import type { StorageRef } from '@icore/shared';
-import { UPLOAD_CLIENT } from './upload-client.module';
+import { UPLOAD_CLIENT } from './upload-client.tokens';
 
 @Injectable()
 export class UploadClientService {

package/templates/libs/upload-client/src/lib/upload-client.tokens.ts

@@ -0,0 +1,4 @@
+// Injection token — kept in its own file so module and service can both
+// import it without creating a circular dependency (which breaks DI in
+// webpack-bundled NestJS apps).
+export const UPLOAD_CLIENT = 'UPLOAD_CLIENT';

package/templates/libs/vite-plugins/src/index.d.mts

@@ -19,3 +19,9 @@ export declare function commonTestConfig(
   name: string,
   coverageDir: string,
 ): NonNullable<UserConfig['test']>;
+
+export declare function commonServer(
+  port: number,
+): NonNullable<import('vite').UserConfig['server']>;
+
+export declare function apiInfoPlugin(opts?: { proxyTarget?: string }): import('vite').Plugin;

package/templates/libs/vite-plugins/src/index.mjs

@@ -104,3 +104,53 @@ export function commonTestConfig(name, coverageDir) {
     },
   };
 }
+
+/**
+ * Shared Vite dev-server config: binds the given port and proxies `/api`
+ * to the gateway (:3001) so the client's relative API base works in dev.
+ * @param {number} port
+ * @returns {import('vite').UserConfig['server']}
+ */
+export function commonServer(port) {
+  return {
+    port,
+    host: 'localhost',
+    proxy: { '/api': { target: 'http://localhost:3001', changeOrigin: true } },
+  };
+}
+
+function box(lines) {
+  const width = Math.max(...lines.map((l) => l.length), 48);
+  const top = `╔═${'═'.repeat(width)}═╗`;
+  const bot = `╚═${'═'.repeat(width)}═╝`;
+  const body = lines.map((l) => `║ ${l.padEnd(width)} ║`).join('\n');
+  return `\n${top}\n${body}\n${bot}`;
+}
+
+/**
+ * Prints a terminal banner on dev-server start showing the API base the client
+ * will use and the gateway proxy target, so misconfiguration is obvious.
+ * @param {{ proxyTarget?: string }} [opts]
+ * @returns {import('vite').Plugin}
+ */
+export function apiInfoPlugin(opts = {}) {
+  const target = opts.proxyTarget ?? 'http://localhost:3001';
+  return {
+    name: 'icore-api-info',
+    apply: 'serve',
+    configureServer(server) {
+      server.httpServer?.once('listening', () => {
+        const explicit = process.env.VITE_API_URL;
+        const lines = explicit
+          ? [`API base: VITE_API_URL = ${explicit}`, '', `(gateway dev-proxy is bypassed)`]
+          : [
+              `API base: /api  →  proxied to ${target}`,
+              '',
+              `Gateway must be running on ${target}.`,
+              `Override with VITE_API_URL in the client .env.`,
+            ];
+        server.config.logger.info(box([`ℹ  iCore client API wiring`, '', ...lines]));
+      });
+    },
+  };
+}

package/templates/package.json

@@ -23,6 +23,7 @@
     "prepare": "husky"
   },
   "devDependencies": {
+    "@icore/vite-plugins": "workspace:*",
     "@eslint/js": "^9.18.0",
     "@nestjs/schematics": "^11.0.0",
     "@nestjs/testing": "^11.0.0",

package/templates/tools/create-icore/_template-shell/package.json

@@ -23,6 +23,7 @@
     "prepare": "husky"
   },
   "devDependencies": {
+    "@icore/vite-plugins": "workspace:*",
     "@eslint/js": "^9.18.0",
     "@nestjs/schematics": "^11.0.0",
     "@nestjs/testing": "^11.0.0",