@idevconn/create-icore 0.4.1 → 0.5.0

package/dist/index.js

@@ -38,6 +38,22 @@ async function rewriteRootPackageJson(targetDir, opts) {
   if (opts.packageManager !== "yarn") {
     delete pkg.packageManager;
   }
+  if (opts.packageManager === "pnpm") {
+    pkg["pnpm"] = {
+      onlyBuiltDependencies: [
+        "@firebase/util",
+        "@nestjs/core",
+        "@parcel/watcher",
+        "@scarf/scarf",
+        "@swc/core",
+        "less",
+        "msgpackr-extract",
+        "nx",
+        "protobufjs",
+        "unrs-resolver"
+      ]
+    };
+  }
   await writeFile(pkgPath, JSON.stringify(pkg, null, 2) + "\n");
 }
 async function writeAuthEnv(targetDir, opts) {
@@ -90,6 +106,14 @@ async function writeRootEnv(targetDir, opts) {
   ];
   await writeFile(join(targetDir, ".env"), lines.join("\n"));
 }
+async function writeClientEnv(targetDir) {
+  const envExample = join(targetDir, "apps/client/.env.example");
+  try {
+    const env = await readFile(envExample, "utf8");
+    await writeFile(join(targetDir, "apps/client/.env"), env);
+  } catch {
+  }
+}
 async function writePaymentEnv(targetDir, opts) {
   if (opts.payment === "none") return;
   const envExample = join(targetDir, "apps/microservices/payment/.env.example");
@@ -466,6 +490,7 @@ async function scaffold(opts, templatesDir) {
   await writeGatewayEnv(opts.targetDir, opts);
   await writeRootEnv(opts.targetDir, opts);
   await selectClientTemplate(opts.targetDir, opts);
+  await writeClientEnv(opts.targetDir);
   if (opts.upload === "none") await removeUploadStack(opts.targetDir);
   if (opts.payment === "none") await removePaymentStack(opts.targetDir);
   if (opts.jobs === "none") await removeJobsStack(opts.targetDir);
@@ -476,9 +501,199 @@ async function scaffold(opts, templatesDir) {
   if (opts.packageManager === "yarn") {
     await writeFile(join(opts.targetDir, "yarn.lock"), "");
   }
+  await writeAiFiles(opts.targetDir, opts);
   if (opts.install) runInstall(opts.targetDir, opts.packageManager);
   if (opts.initGit) gitInit(opts.targetDir, opts.projectName);
 }
+async function writeAiFiles(targetDir, opts) {
+  const pm = opts.packageManager;
+  const nx = pm === "npm" ? "npx nx" : `${pm} nx`;
+  const devCmd = `${pm} dev`;
+  const activeMSes = ["auth (port 4001)"];
+  if (opts.upload !== "none") activeMSes.push(`upload (port 4002)`);
+  if (opts.payment !== "none") activeMSes.push(`payment (port 4003)`);
+  if (opts.example !== "none") activeMSes.push(`notes (port 4004)`);
+  if (opts.jobs !== "none") activeMSes.push(`jobs (standalone)`);
+  const usesSupabase = opts.authProvider === "supabase" || opts.dbProvider === "supabase" || opts.upload === "supabase";
+  const usesFirebase = opts.authProvider === "firebase" || opts.dbProvider === "firebase" || opts.upload === "firebase";
+  await writeFile(join(targetDir, "CLAUDE.md"), "@AGENTS.md\n");
+  const uiLabel = { shadcn: "shadcn/ui + Tailwind", antd: "Ant Design 6", mui: "MUI 6" }[opts.ui];
+  const readme = `# ${opts.projectName}
+
+> Scaffolded with [iCore](https://github.com/iDEVconn/create-icore) \u2014 Nx + NestJS + React full-stack template.
+
+## Stack
+
+| Layer | Technology |
+|-------|-----------|
+| Monorepo | Nx + ${pm} |
+| Gateway | NestJS 11 + Swagger |
+| Auth | ${opts.authProvider} |
+| Database | ${opts.dbProvider} |
+| Upload | ${opts.upload === "none" ? "\u2014" : opts.upload} |
+| UI | ${uiLabel} + TanStack Router + Query |
+| i18n | i18next (en / ru / he) |
+
+## Quick start
+
+\`\`\`bash
+# 1. Fill in provider credentials
+#    apps/microservices/auth/.env
+#    apps/microservices/upload/.env  (if upload is enabled)
+#    apps/client/.env               (VITE_API_URL \u2014 already defaults to /api)
+
+# 2. Start everything
+${devCmd}
+# \u2192 http://localhost:4200        client
+# \u2192 http://localhost:3001/api/docs  Swagger
+\`\`\`
+
+## Commands
+
+\`\`\`bash
+${nx} run <project>:serve   # start a single service
+${nx} test <project>         # unit tests
+${nx} lint <project>         # lint
+${nx} build <project>        # production build
+${pm === "yarn" ? "yarn remove-notes" : pm === "pnpm" ? "pnpm remove-notes" : "npm run remove-notes"}                  # strip the notes sample feature
+\`\`\`
+
+## Scaffolded by
+
+[iCore](https://github.com/iDEVconn/create-icore) \u2014 [@idevconn/create-icore](https://www.npmjs.com/package/@idevconn/create-icore)
+
+## License
+
+Apache-2.0
+`;
+  await writeFile(join(targetDir, "README.md"), readme);
+  const agents = `# ${opts.projectName} \u2014 Agent Instructions
+
+## Stack snapshot
+
+| Dimension  | Choice |
+|------------|--------|
+| Auth       | ${opts.authProvider} |
+| Database   | ${opts.dbProvider} |
+| Upload     | ${opts.upload} |
+| Payment    | ${opts.payment} |
+| Jobs       | ${opts.jobs} |
+| UI         | ${opts.ui} |
+| Transport  | ${opts.transport} |
+| PM         | ${pm} |
+
+## \u{1F680} Mandatory Workflow
+
+- **Branch strategy**: \`dev\` is default. Cut \`feature/<name>\` or \`bug/<name>\` from dev. PRs only target dev. Never push directly to main.
+- **No code without approval**: Propose changes first, wait for go-ahead.
+- **\u0417\u0410\u041A\u041E\u041D \u2014 no crash on missing .env**: MS factories must catch config errors, print a boxed banner with ALL missing vars, and return a Fake strategy in dev. In prod (\`NODE_ENV=production\`) throw the same banner. The \`formatEnvBanner\` + \`missingEnv\` helpers from \`@icore/shared\` handle this.
+- **Post-coding routine**: \`npx prettier --write <files>\` \u2192 \`${nx} lint <project>\` \u2192 \`${nx} build <project>\` \u2014 all green before committing.
+- **Nx generators only**: never hand-write \`project.json\` / tsconfig stacks. Use \`${nx} g @nx/<plugin>:<schematic>\`.
+
+## Architecture
+
+\`\`\`
+apps/
+\u251C\u2500\u2500 api/               NestJS gateway \u2014 all client traffic enters here (:3001)
+\u251C\u2500\u2500 microservices/
+${activeMSes.map((s) => `\u2502   \u251C\u2500\u2500 ${s.split(" ")[0]}/`).join("\n")}
+\u2514\u2500\u2500 client/            Vite + React 19 + ${opts.ui} (:4200)
+libs/
+\u251C\u2500\u2500 shared/            contracts, CASL, transport helpers, env banner utils
+\u251C\u2500\u2500 auth-strategies/${opts.authProvider}/
+${opts.upload !== "none" ? `\u251C\u2500\u2500 storage-strategies/${opts.upload}/
+` : ""}\u251C\u2500\u2500 db-strategies/${opts.dbProvider === "firebase" ? "firestore" : opts.dbProvider}/
+\u251C\u2500\u2500 auth-client/       gateway \u2192 auth MS (TCP/Redis/NATS)
+${opts.upload !== "none" ? `\u251C\u2500\u2500 upload-client/     gateway \u2192 upload MS
+` : ""}\u2514\u2500\u2500 template-shared/   browser-safe React foundation (stores, i18n, CASL)
+\`\`\`
+
+## Key patterns
+
+**Strategy swap** \u2014 provider is chosen at runtime via env. Never import a concrete strategy in app code; always inject via the factory token (\`AuthStrategy\`, \`StorageStrategy\`, \`DBStrategy\`).
+
+**Transport** \u2014 \`buildTransport(prefix)\` reads \`${opts.transport.toUpperCase()}*\` vars. Same helper on gateway client-modules and each MS \`main.ts\`. Supports tcp / redis / nats \u2014 change by flipping \`*_TRANSPORT\` in \`.env\`.
+
+**Env layering**:
+1. Root \`.env\` \u2014 \`DB_PROVIDER\`
+2. \`apps/api/.env\` \u2014 gateway transport endpoints
+3. \`apps/microservices/<name>/.env\` \u2014 each MS provider + transport
+4. \`apps/client/.env\` \u2014 \`VITE_API_URL\`
+
+## Commands
+
+\`\`\`bash
+${devCmd}                     # start all services
+${nx} run api:serve           # gateway only
+${nx} run auth:serve          # auth MS only
+${nx} test <project>          # run tests
+${nx} lint <project>          # lint
+${nx} build <project>         # build
+${nx} g @nx/nest:resource     # generate NestJS resource
+\`\`\`
+
+## .env files to configure
+
+| File | Key vars |
+|------|----------|
+| \`apps/microservices/auth/.env\` | \`AUTH_PROVIDER=${opts.authProvider}\`, ${opts.authProvider === "supabase" ? "`SUPABASE_URL`, `SUPABASE_SERVICE_ROLE_KEY`" : "`FB_ADMIN_*`, `FIREBASE_WEB_API_KEY`"} |
+${opts.upload !== "none" ? `| \`apps/microservices/upload/.env\` | \`STORAGE_PROVIDER=${opts.upload}\`, provider creds |
+` : ""}| \`apps/microservices/notes/.env\` | \`DB_PROVIDER=${opts.dbProvider}\`, DB creds |
+| \`apps/client/.env\` | \`VITE_API_URL=/api\` (proxied to :3001 in dev) |
+
+## Testing
+
+- Unit tests: Vitest, files named \`*.unit.test.ts(x)\` in \`__tests__/\` next to source.
+- Test behaviour, not implementation. Fake strategies from \`@icore/shared\` (FakeAuthStrategy etc.) serve as test doubles.
+- Run: \`${nx} test <project>\`
+`;
+  await writeFile(join(targetDir, "AGENTS.md"), agents);
+  await mkdir(join(targetDir, ".claude"), { recursive: true });
+  const mcpServers = {
+    nx: {
+      command: "npx",
+      args: ["-y", "@nx/mcp@latest", "--directory", "."],
+      type: "stdio"
+    }
+  };
+  if (usesSupabase) {
+    mcpServers["supabase"] = {
+      command: "npx",
+      args: [
+        "-y",
+        "@supabase/mcp-server-supabase@latest",
+        "--access-token",
+        "<SUPABASE_PERSONAL_ACCESS_TOKEN>"
+      ],
+      type: "stdio"
+    };
+  }
+  if (usesFirebase) {
+    mcpServers["firebase"] = {
+      command: "npx",
+      args: ["-y", "firebase-tools@latest", "experimental:mcp"],
+      type: "stdio"
+    };
+  }
+  const nxCmds = [`Bash(${nx} *)`, `Bash(${devCmd})`];
+  if (pm !== "npm") nxCmds.push(`Bash(npx nx *)`);
+  const settings = {
+    mcpServers,
+    permissions: {
+      allow: [
+        ...nxCmds,
+        "Bash(npx prettier *)",
+        "Bash(git status)",
+        "Bash(git diff *)",
+        "Bash(git log *)"
+      ]
+    }
+  };
+  await writeFile(
+    join(targetDir, ".claude", "settings.json"),
+    JSON.stringify(settings, null, 2) + "\n"
+  );
+}
 
 // src/lib/prompts.ts
 import * as p from "@clack/prompts";
@@ -674,6 +889,12 @@ Re-run with @latest to refresh:
   });
   if (p.isCancel(transport)) throw new Error("cancelled");
   const packageManager = flags.packageManager ?? detectPackageManager();
+  if (packageManager === "yarn") {
+    p.note(
+      "yarn 4.15+ enforces a 24h publish-age gate (npmMinimalAgeGate=1d), so a\n`yarn create @idevconn/icore@latest` run within 24h of a release resolves an\nolder version. If the banner above shows an unexpectedly old version, either:\n  \u2022 wait \u2014 the version auto-unlocks 24h after publish, or\n  \u2022 bypass once:  yarn config set npmMinimalAgeGate 0  (then re-run), or\n  \u2022 use npm/pnpm: npm init @idevconn/icore@latest <name> -- [flags]",
+      "\u26A0 yarn 24h age-gate"
+    );
+  }
   const initGit = flags.initGit ?? !await p.confirm({ message: "Initialise git repo?", initialValue: true }) === false;
   const install = flags.install ?? !await p.confirm({
     message: `Run ${packageManager} install?`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@idevconn/create-icore",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "description": "Bootstrap a new project from the iCore scaffold (Nx + NestJS + React + Vite + shadcn/Tailwind, swappable auth + storage providers).",
   "license": "Apache-2.0",
   "author": "iDEVconn",

package/templates/apps/api/src/app/app.module.ts

@@ -1,3 +1,4 @@
+import { join } from 'node:path';
 import { Module } from '@nestjs/common';
 import { ConfigModule } from '@nestjs/config';
 import { ThrottlerModule, seconds } from '@nestjs/throttler';
@@ -11,7 +12,10 @@ import { AdminModule } from './admin/admin.module';
 
 @Module({
   imports: [
-    ConfigModule.forRoot({ isGlobal: true }),
+    ConfigModule.forRoot({
+      isGlobal: true,
+      envFilePath: [join(process.cwd(), 'apps/api/.env'), join(process.cwd(), '.env')],
+    }),
     ThrottlerModule.forRoot([{ name: 'auth-burst', ttl: seconds(60), limit: 10 }]),
     AuthModule,
     AbilitiesModule,

package/templates/apps/api/src/main.ts

@@ -3,9 +3,17 @@ import { NestFactory } from '@nestjs/core';
 import { NestExpressApplication } from '@nestjs/platform-express';
 import { DocumentBuilder, SwaggerModule } from '@nestjs/swagger';
 import cookieParser from 'cookie-parser';
+import { formatGatewayBanner } from '@icore/shared';
 import { AppModule } from './app/app.module';
 import pkg from '@icore/package.json';
 
+const GATEWAY_SERVICES = [
+  { name: 'auth', prefix: 'AUTH' },
+  { name: 'upload', prefix: 'UPLOAD' },
+  { name: 'notes', prefix: 'NOTES' },
+  { name: 'payment', prefix: 'PAYMENT' },
+];
+
 const DEFAULT_PORT = 3001;
 
 async function bootstrap() {
@@ -28,12 +36,10 @@ async function bootstrap() {
 
 bootstrap()
   .then(() => {
-    const logger = new Logger('API-Bootstrap');
-    logger.log(
-      `API Bootstrap completed successfully: ${process.env.API_ORIGIN ?? 'http://localhost'}:${process.env.API_PORT ?? DEFAULT_PORT}/api`,
-    );
-    logger.log(
-      `Swagger UI: ${process.env.API_ORIGIN ?? 'http://localhost'}:${process.env.API_PORT ?? DEFAULT_PORT}/api/docs`,
+    const origin = process.env.API_ORIGIN ?? 'http://localhost';
+    const port = Number(process.env.API_PORT ?? DEFAULT_PORT);
+    new Logger('API-Bootstrap').log(
+      formatGatewayBanner({ port, origin, services: GATEWAY_SERVICES }),
     );
   })
   .catch((err) => {

package/templates/apps/microservices/auth/project.json

@@ -50,7 +50,8 @@
       "dependsOn": ["build"],
       "options": {
         "buildTarget": "auth:build",
-        "runBuildTargetDependencies": false
+        "runBuildTargetDependencies": false,
+        "port": 9230
       },
       "configurations": {
         "development": {

package/templates/apps/microservices/auth/src/app/app.module.ts

@@ -5,15 +5,26 @@ import { createClient } from '@supabase/supabase-js';
 import * as admin from 'firebase-admin';
 import { SupabaseAuthStrategy } from '@icore/auth-supabase';
 import { FirebaseAuthStrategy, HttpIdentityToolkitClient } from '@icore/auth-firebase';
-import { FakeAuthStrategy } from '@icore/shared';
+import { FakeAuthStrategy, missingEnv, formatEnvBanner } from '@icore/shared';
 import type { AuthStrategy } from '@icore/shared';
 import { Logger } from '@nestjs/common';
 import { AuthController } from './auth.controller';
 
+const ENV_PATH = 'apps/microservices/auth/.env';
+
+// Env vars each provider needs (besides AUTH_PROVIDER itself).
+const REQUIRED_ENV: Record<string, string[]> = {
+  supabase: ['SUPABASE_URL', 'SUPABASE_SERVICE_ROLE_KEY'],
+  firebase: [
+    'FB_ADMIN_PROJECT_ID',
+    'FB_ADMIN_CLIENT_EMAIL',
+    'FB_ADMIN_PRIVATE_KEY',
+    'FIREBASE_WEB_API_KEY',
+  ],
+};
+
 function requireEnv(cfg: ConfigService, key: string): string {
-  const val = cfg.getOrThrow<string>(key);
-  if (!val) throw new Error(`${key} is not set — check apps/microservices/auth/.env`);
-  return val;
+  return cfg.getOrThrow<string>(key);
 }
 
 function makeFirebaseStrategy(cfg: ConfigService): AuthStrategy {
@@ -49,28 +60,41 @@ function makeFirebaseStrategy(cfg: ConfigService): AuthStrategy {
     {
       provide: 'AuthStrategy',
       useFactory: (cfg: ConfigService): AuthStrategy => {
+        const logger = new Logger('AuthStrategy');
+        const provider = cfg.get<string>('AUTH_PROVIDER')?.trim();
+        const keys = provider ? REQUIRED_ENV[provider] : undefined;
+        const missing = keys ? missingEnv((k) => cfg.get<string>(k), keys) : [];
+
+        // Prod: fail fast — never silently run a fake auth strategy.
+        // Dev: warn with a boxed banner + fall back to the in-memory fake.
+        const fallback = (reason?: string): AuthStrategy => {
+          const banner = formatEnvBanner({
+            service: 'auth MS',
+            provider,
+            missing,
+            envPath: ENV_PATH,
+            reason,
+          });
+          if (process.env.NODE_ENV === 'production') throw new Error(banner);
+          logger.warn(banner);
+          return new FakeAuthStrategy();
+        };
+
+        if (!keys || missing.length > 0) return fallback();
+
         try {
-          const provider = requireEnv(cfg, 'AUTH_PROVIDER');
-          switch (provider) {
-            case 'supabase': {
-              const client = createClient(
-                requireEnv(cfg, 'SUPABASE_URL'),
-                requireEnv(cfg, 'SUPABASE_SERVICE_ROLE_KEY'),
-                { auth: { autoRefreshToken: false, persistSession: false } },
-              );
-              return new SupabaseAuthStrategy({ client });
-            }
-            case 'firebase':
-              return makeFirebaseStrategy(cfg);
-            default:
-              throw new Error(`Unsupported AUTH_PROVIDER: ${provider}`);
+          if (provider === 'supabase') {
+            const client = createClient(
+              requireEnv(cfg, 'SUPABASE_URL'),
+              requireEnv(cfg, 'SUPABASE_SERVICE_ROLE_KEY'),
+              { auth: { autoRefreshToken: false, persistSession: false } },
+            );
+            return new SupabaseAuthStrategy({ client });
           }
+          return makeFirebaseStrategy(cfg);
         } catch (err) {
-          new Logger('AuthStrategy').warn(
-            `Not configured: ${err instanceof Error ? err.message : String(err)}. ` +
-              `Requests will fail until apps/microservices/auth/.env is set.`,
-          );
-          return new FakeAuthStrategy();
+          // Vars present but invalid (e.g. placeholder URL the SDK rejects).
+          return fallback(err instanceof Error ? err.message : String(err));
         }
       },
       inject: [ConfigService],

package/templates/apps/microservices/jobs/project.json

@@ -50,7 +50,8 @@
       "dependsOn": ["build"],
       "options": {
         "buildTarget": "jobs:build",
-        "runBuildTargetDependencies": false
+        "runBuildTargetDependencies": false,
+        "port": 9234
       },
       "configurations": {
         "development": {

package/templates/apps/microservices/notes/project.json

@@ -50,7 +50,8 @@
       "dependsOn": ["build"],
       "options": {
         "buildTarget": "notes:build",
-        "runBuildTargetDependencies": false
+        "runBuildTargetDependencies": false,
+        "port": 9232
       },
       "configurations": {
         "development": {

package/templates/apps/microservices/notes/src/app/app.module.ts

@@ -5,15 +5,22 @@ import { createClient } from '@supabase/supabase-js';
 import * as admin from 'firebase-admin';
 import { SupabaseDBStrategy } from '@icore/db-supabase';
 import { FirestoreDBStrategy } from '@icore/db-firestore';
-import { FakeDBStrategy } from '@icore/shared';
+import { FakeDBStrategy, missingEnv, formatEnvBanner } from '@icore/shared';
 import type { DBStrategy } from '@icore/shared';
 import { Logger } from '@nestjs/common';
 import { NotesController } from './notes.controller';
 
+const ENV_PATH = 'apps/microservices/notes/.env';
+
+// DB_PROVIDER accepts supabase | firestore | firebase (latter two are Firestore).
+const REQUIRED_ENV: Record<string, string[]> = {
+  supabase: ['SUPABASE_URL', 'SUPABASE_SERVICE_ROLE_KEY'],
+  firestore: ['FB_ADMIN_PROJECT_ID', 'FB_ADMIN_CLIENT_EMAIL', 'FB_ADMIN_PRIVATE_KEY'],
+  firebase: ['FB_ADMIN_PROJECT_ID', 'FB_ADMIN_CLIENT_EMAIL', 'FB_ADMIN_PRIVATE_KEY'],
+};
+
 function requireEnv(cfg: ConfigService, key: string): string {
-  const val = cfg.getOrThrow<string>(key);
-  if (!val) throw new Error(`${key} is not set — check apps/microservices/notes/.env`);
-  return val;
+  return cfg.getOrThrow<string>(key);
 }
 
 @Module({
@@ -31,8 +38,27 @@ function requireEnv(cfg: ConfigService, key: string): string {
     {
       provide: 'DBStrategy',
       useFactory: (cfg: ConfigService): DBStrategy => {
+        const logger = new Logger('DBStrategy');
+        const provider = cfg.get<string>('DB_PROVIDER')?.trim();
+        const keys = provider ? REQUIRED_ENV[provider] : undefined;
+        const missing = keys ? missingEnv((k) => cfg.get<string>(k), keys) : [];
+
+        const fallback = (reason?: string): DBStrategy => {
+          const banner = formatEnvBanner({
+            service: 'notes MS',
+            provider,
+            missing,
+            envPath: ENV_PATH,
+            reason,
+          });
+          if (process.env.NODE_ENV === 'production') throw new Error(banner);
+          logger.warn(banner);
+          return new FakeDBStrategy();
+        };
+
+        if (!keys || missing.length > 0) return fallback();
+
         try {
-          const provider = requireEnv(cfg, 'DB_PROVIDER');
           if (provider === 'supabase') {
             const client = createClient(
               requireEnv(cfg, 'SUPABASE_URL'),
@@ -41,29 +67,22 @@ function requireEnv(cfg: ConfigService, key: string): string {
             );
             return new SupabaseDBStrategy({ client });
           }
-          if (provider === 'firestore' || provider === 'firebase') {
-            if (admin.apps.length === 0) {
-              admin.initializeApp({
-                credential: admin.credential.cert({
-                  projectId: requireEnv(cfg, 'FB_ADMIN_PROJECT_ID'),
-                  clientEmail: requireEnv(cfg, 'FB_ADMIN_CLIENT_EMAIL'),
-                  privateKey: requireEnv(cfg, 'FB_ADMIN_PRIVATE_KEY').replace(/\\n/g, '\n'),
-                }),
-              });
-            }
-            return new FirestoreDBStrategy({
-              db: admin.firestore() as unknown as ConstructorParameters<
-                typeof FirestoreDBStrategy
-              >[0]['db'],
+          if (admin.apps.length === 0) {
+            admin.initializeApp({
+              credential: admin.credential.cert({
+                projectId: requireEnv(cfg, 'FB_ADMIN_PROJECT_ID'),
+                clientEmail: requireEnv(cfg, 'FB_ADMIN_CLIENT_EMAIL'),
+                privateKey: requireEnv(cfg, 'FB_ADMIN_PRIVATE_KEY').replace(/\\n/g, '\n'),
+              }),
             });
           }
-          throw new Error(`Unsupported DB_PROVIDER: ${provider}`);
+          return new FirestoreDBStrategy({
+            db: admin.firestore() as unknown as ConstructorParameters<
+              typeof FirestoreDBStrategy
+            >[0]['db'],
+          });
         } catch (err) {
-          new Logger('DBStrategy').warn(
-            `Not configured: ${err instanceof Error ? err.message : String(err)}. ` +
-              `Requests will fail until apps/microservices/notes/.env is set.`,
-          );
-          return new FakeDBStrategy();
+          return fallback(err instanceof Error ? err.message : String(err));
         }
       },
       inject: [ConfigService],

package/templates/apps/microservices/payment/project.json

@@ -50,7 +50,8 @@
       "dependsOn": ["build"],
       "options": {
         "buildTarget": "payment:build",
-        "runBuildTargetDependencies": false
+        "runBuildTargetDependencies": false,
+        "port": 9233
       },
       "configurations": {
         "development": {

package/templates/apps/microservices/payment/src/app/app.module.ts

@@ -1,9 +1,16 @@
 import { join } from 'node:path';
-import { Module } from '@nestjs/common';
+import { Module, Logger } from '@nestjs/common';
 import { ConfigModule, ConfigService } from '@nestjs/config';
 import { PaymentRegistry, PaypalStrategy, createPayment } from '@idevconn/payment';
+import { missingEnv, formatEnvBanner } from '@icore/shared';
 import { PaymentController } from './payment.controller';
 
+const ENV_PATH = 'apps/microservices/payment/.env';
+
+const REQUIRED_ENV: Record<string, string[]> = {
+  paypal: ['PAYPAL_CLIENT_ID', 'PAYPAL_CLIENT_SECRET'],
+};
+
 @Module({
   imports: [
     ConfigModule.forRoot({
@@ -19,19 +26,35 @@ import { PaymentController } from './payment.controller';
     {
       provide: PaymentRegistry,
       useFactory: (cfg: ConfigService) => {
-        const provider = cfg.get<string>('PAYMENT_PROVIDER') ?? 'paypal';
-        if (provider === 'paypal') {
-          return createPayment({
-            strategies: {
-              paypal: new PaypalStrategy({
-                clientId: cfg.getOrThrow<string>('PAYPAL_CLIENT_ID'),
-                secret: cfg.getOrThrow<string>('PAYPAL_CLIENT_SECRET'),
-                environment: cfg.get<'sandbox' | 'live'>('PAYPAL_ENVIRONMENT') ?? 'sandbox',
-              }),
-            },
+        const logger = new Logger('PaymentRegistry');
+        const provider = (cfg.get<string>('PAYMENT_PROVIDER') ?? 'paypal').trim();
+        const keys = REQUIRED_ENV[provider];
+        if (!keys) throw new Error(`Unsupported PAYMENT_PROVIDER: ${provider}`);
+
+        const missing = missingEnv((k) => cfg.get<string>(k), keys);
+        if (missing.length > 0) {
+          const banner = formatEnvBanner({
+            service: 'payment MS',
+            provider,
+            missing,
+            envPath: ENV_PATH,
+            headline: `⚠  payment MS — ${provider} credentials missing (payments will fail)`,
           });
+          // Prod: fail fast. Dev: warn — PayPal is lazy, so the MS still boots
+          // and only payment calls fail until creds are set.
+          if (process.env.NODE_ENV === 'production') throw new Error(banner);
+          logger.warn(banner);
         }
-        throw new Error(`Unsupported PAYMENT_PROVIDER: ${provider}`);
+
+        return createPayment({
+          strategies: {
+            paypal: new PaypalStrategy({
+              clientId: cfg.get<string>('PAYPAL_CLIENT_ID') ?? '',
+              secret: cfg.get<string>('PAYPAL_CLIENT_SECRET') ?? '',
+              environment: cfg.get<'sandbox' | 'live'>('PAYPAL_ENVIRONMENT') ?? 'sandbox',
+            }),
+          },
+        });
       },
       inject: [ConfigService],
     },

package/templates/apps/microservices/upload/project.json

@@ -50,7 +50,8 @@
       "dependsOn": ["build"],
       "options": {
         "buildTarget": "upload:build",
-        "runBuildTargetDependencies": false
+        "runBuildTargetDependencies": false,
+        "port": 9231
       },
       "configurations": {
         "development": {