@idevconn/create-icore 0.4.1 → 0.5.1

package/dist/index.js

@@ -1,3 +1,8 @@
+// src/lib/options.ts
+function pmRun(pm, script) {
+  return pm === "npm" ? `npm run ${script}` : `${pm} ${script}`;
+}
+
 // src/lib/scaffold.ts
 import { copyFile, mkdir, readdir, readFile, stat, writeFile, rm } from "fs/promises";
 import { readFileSync } from "fs";
@@ -35,9 +40,29 @@ async function rewriteRootPackageJson(targetDir, opts) {
   pkg["version"] = "0.0.1";
   pkg["private"] = true;
   delete pkg.description;
+  if (opts.transport === "nats") {
+    const deps = pkg["dependencies"] ??= {};
+    deps["nats"] = "^2.29.3";
+  }
   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) {
@@ -75,9 +100,9 @@ async function writeNotesEnv(targetDir, opts) {
 async function writeGatewayEnv(targetDir, opts) {
   const envExample = join(targetDir, "apps/api/.env.example");
   const env = await readFile(envExample, "utf8");
-  let next = env.replace(/^AUTH_TRANSPORT=.*$/m, `AUTH_TRANSPORT=${opts.transport}`).replace(/^UPLOAD_TRANSPORT=.*$/m, `UPLOAD_TRANSPORT=${opts.transport}`);
+  let next = env.replace(/^AUTH_TRANSPORT=.*$/m, `AUTH_TRANSPORT=${opts.transport}`).replace(/^UPLOAD_TRANSPORT=.*$/m, `UPLOAD_TRANSPORT=${opts.transport}`).replace(/^NOTES_TRANSPORT=.*$/m, `NOTES_TRANSPORT=${opts.transport}`).replace(/^PAYMENT_TRANSPORT=.*$/m, `PAYMENT_TRANSPORT=${opts.transport}`);
   if (opts.transport !== "tcp") {
-    next = next.replace(/^# (AUTH_(?:REDIS|NATS)_URL=)/m, "$1").replace(/^# (UPLOAD_(?:REDIS|NATS)_URL=)/m, "$1");
+    next = next.replace(/^# (AUTH_(?:REDIS|NATS)_URL=)/m, "$1").replace(/^# (UPLOAD_(?:REDIS|NATS)_URL=)/m, "$1").replace(/^# (NOTES_(?:REDIS|NATS)_URL=)/m, "$1").replace(/^# (PAYMENT_(?:REDIS|NATS)_URL=)/m, "$1");
   }
   await writeFile(join(targetDir, "apps/api/.env"), next);
 }
@@ -90,6 +115,25 @@ async function writeRootEnv(targetDir, opts) {
   ];
   await writeFile(join(targetDir, ".env"), lines.join("\n"));
 }
+async function stripGatewayTransport(targetDir, prefix) {
+  const gatewayEnv = join(targetDir, "apps/api/.env");
+  try {
+    const env = await readFile(gatewayEnv, "utf8");
+    const next = env.split("\n").filter(
+      (line) => !line.startsWith(`${prefix}_`) && !line.startsWith(`# ${prefix}_`) && !line.includes(`${prefix} MS transport`)
+    ).join("\n");
+    await writeFile(gatewayEnv, next);
+  } catch {
+  }
+}
+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");
@@ -166,6 +210,7 @@ async function removePaymentStack(targetDir) {
     "@icore/payment-client",
     "@idevconn/payment"
   ]);
+  await stripGatewayTransport(targetDir, "PAYMENT");
 }
 async function removeNotesStack(targetDir) {
   for (const p2 of [
@@ -187,6 +232,7 @@ async function removeNotesStack(targetDir) {
   } catch {
   }
   await stripDeps(join(targetDir, "apps/api/package.json"), ["@icore/notes-client"]);
+  await stripGatewayTransport(targetDir, "NOTES");
   const tsconfigPath = join(targetDir, "tsconfig.base.json");
   try {
     const src = await readFile(tsconfigPath, "utf8");
@@ -243,15 +289,17 @@ async function stripTsconfigPath(targetDir, alias) {
 }
 async function removeUnusedAuthStrategies(targetDir, authProvider) {
   const modulePath = join(targetDir, "apps/microservices/auth/src/app/app.module.ts");
+  const AUTH_BRANCH = /if \(provider === 'supabase'\) return makeSupabaseAuth\(cfg\);\n\s*return makeFirebaseAuth\(cfg\);/m;
   if (authProvider === "supabase") {
     await rm(join(targetDir, "libs/auth-strategies/firebase"), { recursive: true, force: true });
     await stripDeps(join(targetDir, "apps/microservices/auth/package.json"), [
-      "@icore/auth-firebase"
+      "@icore/auth-firebase",
+      "@icore/firebase-admin"
     ]);
     await stripTsconfigPath(targetDir, "@icore/auth-firebase");
     try {
       const src = await readFile(modulePath, "utf8");
-      const next = src.replace(/^import \* as admin from 'firebase-admin';\n/m, "").replace(/^import \{[^}]*FirebaseAuthStrategy[^}]*\} from '@icore\/auth-firebase';\n/m, "").replace(/^function makeFirebaseStrategy\b[\s\S]*?\n^}\n/m, "").replace(/(?<=\n) *case 'firebase':\n *return makeFirebaseStrategy\(cfg\);\n/, "");
+      const next = src.replace(/^import \{[^}]*\} from '@icore\/firebase-admin';\n/m, "").replace(/^import \{[^}]*FirebaseAuthStrategy[^}]*\} from '@icore\/auth-firebase';\n/m, "").replace(/^ {2}firebase: \[[^\]]*\],\n/m, "").replace(/\nfunction makeFirebaseAuth[\s\S]*?\n}\n/m, "").replace(AUTH_BRANCH, "return makeSupabaseAuth(cfg);");
       await writeFile(modulePath, next);
     } catch {
     }
@@ -264,10 +312,7 @@ async function removeUnusedAuthStrategies(targetDir, authProvider) {
     await stripTsconfigPath(targetDir, "@icore/auth-supabase");
     try {
       const src = await readFile(modulePath, "utf8");
-      const next = src.replace(/^import \{ createClient \} from '@supabase\/supabase-js';\n/m, "").replace(/^import \{[^}]*SupabaseAuthStrategy[^}]*\} from '@icore\/auth-supabase';\n/m, "").replace(
-        /\n {10}case 'supabase': \{[\s\S]*?return new SupabaseAuthStrategy\(\{ client \}\);\n {10}\}\n/m,
-        ""
-      );
+      const next = src.replace(/^import \{ createClient \} from '@supabase\/supabase-js';\n/m, "").replace(/^import \{[^}]*SupabaseAuthStrategy[^}]*\} from '@icore\/auth-supabase';\n/m, "").replace(/\nfunction makeSupabaseAuth[\s\S]*?\n}\n/m, "").replace(AUTH_BRANCH, "return makeFirebaseAuth(cfg);");
       await writeFile(modulePath, next);
     } catch {
     }
@@ -279,7 +324,8 @@ async function removeUnusedStorageStrategies(targetDir, uploadProvider) {
   if (uploadProvider !== "firebase") {
     await rm(join(targetDir, "libs/storage-strategies/firebase"), { recursive: true, force: true });
     await stripDeps(join(targetDir, "apps/microservices/upload/package.json"), [
-      "@icore/storage-firebase"
+      "@icore/storage-firebase",
+      "@icore/firebase-admin"
     ]);
     await stripTsconfigPath(targetDir, "@icore/storage-firebase");
   }
@@ -303,26 +349,26 @@ async function removeUnusedStorageStrategies(targetDir, uploadProvider) {
   try {
     let src = await readFile(modulePath, "utf8");
     if (uploadProvider !== "firebase") {
-      src = src.replace(/^import \* as admin from 'firebase-admin';\n/m, "").replace(
+      src = src.replace(/^import \{[^}]*\} from '@icore\/firebase-admin';\n/m, "").replace(
         /^import \{[^}]*FirebaseStorageStrategy[^}]*\} from '@icore\/storage-firebase';\n/m,
         ""
-      ).replace(/^function makeFirebaseStorage\b[\s\S]*?\n^}\n/m, "").replace(/(?<=\n) *case 'firebase':\n *return makeFirebaseStorage\(cfg\);\n/, "");
+      ).replace(/^ {2}firebase: \[[^\]]*\],\n/m, "").replace(/\nfunction makeFirebaseStorage[\s\S]*?\n}\n/m, "");
     }
     if (uploadProvider !== "cloudinary") {
       src = src.replace(/^import \{ v2 as cloudinary \} from 'cloudinary';\n/m, "").replace(
         /^import \{[^}]*CloudinaryStorageStrategy[^}]*\} from '@icore\/storage-cloudinary';\n/m,
         ""
-      ).replace(/^function makeCloudinaryStorage\b[\s\S]*?\n^}\n/m, "").replace(/(?<=\n) *case 'cloudinary':\n *return makeCloudinaryStorage\(cfg\);\n/, "");
+      ).replace(/\nfunction makeCloudinaryStorage[\s\S]*?\n}\n/m, "");
     }
     if (uploadProvider !== "supabase") {
       src = src.replace(/^import \{ createClient \} from '@supabase\/supabase-js';\n/m, "").replace(
         /^import \{[^}]*SupabaseStorageStrategy[^}]*\} from '@icore\/storage-supabase';\n/m,
         ""
-      ).replace(
-        /\n {10}case 'supabase': \{[\s\S]*?bucket: requireEnv\(cfg, 'SUPABASE_STORAGE_BUCKET'\),\n {12}\}\);\n {10}\}\n/m,
-        ""
-      );
+      ).replace(/\nfunction makeSupabaseStorage[\s\S]*?\n}\n/m, "");
     }
+    const STORAGE_BRANCH = /if \(provider === 'supabase'\) return makeSupabaseStorage\(cfg\);\n\s*if \(provider === 'firebase'\) return makeFirebaseStorage\(cfg\);\n\s*return makeCloudinaryStorage\(cfg\);/m;
+    const chosenReturn = `return make${uploadProvider.charAt(0).toUpperCase() + uploadProvider.slice(1)}Storage(cfg);`;
+    src = src.replace(STORAGE_BRANCH, chosenReturn);
     await writeFile(modulePath, src);
   } catch {
   }
@@ -332,14 +378,15 @@ async function removeUnusedDbStrategies(targetDir, dbProvider) {
   if (dbProvider === "supabase") {
     await rm(join(targetDir, "libs/db-strategies/firestore"), { recursive: true, force: true });
     await stripDeps(join(targetDir, "apps/microservices/notes/package.json"), [
-      "@icore/db-firestore"
+      "@icore/db-firestore",
+      "@icore/firebase-admin"
     ]);
     await stripTsconfigPath(targetDir, "@icore/db-firestore");
     try {
       const src = await readFile(modulePath, "utf8");
-      const next = src.replace(/^import \* as admin from 'firebase-admin';\n/m, "").replace(/^import \{[^}]*FirestoreDBStrategy[^}]*\} from '@icore\/db-firestore';\n/m, "").replace(
-        /\n {8}if \(provider === 'firestore'[\s\S]*?return new FirestoreDBStrategy\(\{[\s\S]*?\}\);\n {8}\}\n/m,
-        ""
+      const next = src.replace(/^import \{[^}]*\} from '@icore\/firebase-admin';\n/m, "").replace(/^import \{[^}]*FirestoreDBStrategy[^}]*\} from '@icore\/db-firestore';\n/m, "").replace(/^ {2}firestore: \[[^\]]*\],\n/m, "").replace(/^ {2}firebase: \[[^\]]*\],\n/m, "").replace(/\nfunction makeFirestoreDB[\s\S]*?\n}\n/m, "").replace(
+        /if \(provider === 'supabase'\) return makeSupabaseDB\(cfg\);\n\s*return makeFirestoreDB\(cfg\);/m,
+        "return makeSupabaseDB(cfg);"
       );
       await writeFile(modulePath, next);
     } catch {
@@ -353,15 +400,19 @@ async function removeUnusedDbStrategies(targetDir, dbProvider) {
     await stripTsconfigPath(targetDir, "@icore/db-supabase");
     try {
       const src = await readFile(modulePath, "utf8");
-      const next = src.replace(/^import \{ createClient \} from '@supabase\/supabase-js';\n/m, "").replace(/^import \{[^}]*SupabaseDBStrategy[^}]*\} from '@icore\/db-supabase';\n/m, "").replace(
-        /\n {8}if \(provider === 'supabase'\) \{[\s\S]*?return new SupabaseDBStrategy\(\{ client \}\);\n {8}\}\n/m,
-        ""
+      const next = src.replace(/^import \{ createClient \} from '@supabase\/supabase-js';\n/m, "").replace(/^import \{[^}]*SupabaseDBStrategy[^}]*\} from '@icore\/db-supabase';\n/m, "").replace(/\nfunction makeSupabaseDB[\s\S]*?\n}\n/m, "").replace(
+        /if \(provider === 'supabase'\) return makeSupabaseDB\(cfg\);\n\s*return makeFirestoreDB\(cfg\);/m,
+        "return makeFirestoreDB(cfg);"
       );
       await writeFile(modulePath, next);
     } catch {
     }
   }
 }
+async function removeFirebaseAdminLib(targetDir) {
+  await rm(join(targetDir, "libs/firebase-admin"), { recursive: true, force: true });
+  await stripTsconfigPath(targetDir, "@icore/firebase-admin");
+}
 async function removeUploadStack(targetDir) {
   const paths = [
     "apps/microservices/upload",
@@ -466,6 +517,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);
@@ -473,12 +525,230 @@ async function scaffold(opts, templatesDir) {
   await removeUnusedAuthStrategies(opts.targetDir, opts.authProvider);
   await removeUnusedStorageStrategies(opts.targetDir, opts.upload);
   await removeUnusedDbStrategies(opts.targetDir, opts.dbProvider);
+  const firebaseUsed = opts.authProvider === "firebase" || opts.dbProvider === "firebase" || opts.upload === "firebase";
+  if (!firebaseUsed) await removeFirebaseAdminLib(opts.targetDir);
   if (opts.packageManager === "yarn") {
     await writeFile(join(opts.targetDir, "yarn.lock"), "");
+  } else {
+    await rm(join(opts.targetDir, ".yarn"), { recursive: true, force: true });
+    await rm(join(opts.targetDir, ".yarnrc.yml"), { force: true });
   }
+  await patchGitignoreForPm(opts.targetDir, opts.packageManager);
+  await writeAiFiles(opts.targetDir, opts);
   if (opts.install) runInstall(opts.targetDir, opts.packageManager);
   if (opts.initGit) gitInit(opts.targetDir, opts.projectName);
 }
+async function patchGitignoreForPm(targetDir, pm) {
+  const giPath = join(targetDir, ".gitignore");
+  try {
+    let src = await readFile(giPath, "utf8");
+    src = src.replace(/^# Build artifacts.*\ntools\/create-icore\/templates\/\s*\n/m, "");
+    if (pm !== "yarn") {
+      src = src.replace(/^\.yarn\/\*\s*\n/m, "").replace(/^!\.yarn\/patches\s*\n/m, "").replace(/^!\.yarn\/plugins\s*\n/m, "").replace(/^!\.yarn\/releases\s*\n/m, "").replace(/^!\.yarn\/sdks\s*\n/m, "").replace(/^!\.yarn\/versions\s*\n/m, "").replace(/^\.pnp\.\*\s*\n/m, "");
+    }
+    if (pm === "pnpm") {
+      if (!src.includes(".pnpm-debug.log")) {
+        src += "\n# pnpm\n.pnpm-debug.log*\n";
+      }
+    }
+    if (pm === "npm") {
+      if (!src.includes("npm-debug.log")) {
+        src += "\n# npm\nnpm-debug.log*\n";
+      }
+    }
+    await writeFile(giPath, src);
+  } catch {
+  }
+}
+async function writeAiFiles(targetDir, opts) {
+  const pm = opts.packageManager;
+  const nx = pm === "npm" ? "npx nx" : `${pm} nx`;
+  const devCmd = pmRun(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 +944,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?`,
@@ -697,5 +973,6 @@ Re-run with @latest to refresh:
 }
 export {
   collectOptions,
+  pmRun,
   scaffold
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@idevconn/create-icore",
-  "version": "0.4.1",
+  "version": "0.5.1",
   "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/.env.example

@@ -15,5 +15,19 @@ UPLOAD_PORT=4002
 # UPLOAD_REDIS_URL=redis://localhost:6379
 # UPLOAD_NATS_URL=nats://localhost:4222
 
+# Notes MS transport — must match apps/microservices/notes/.env
+NOTES_TRANSPORT=tcp
+NOTES_HOST=127.0.0.1
+NOTES_PORT=4004
+# NOTES_REDIS_URL=redis://localhost:6379
+# NOTES_NATS_URL=nats://localhost:4222
+
+# Payment MS transport — must match apps/microservices/payment/.env
+PAYMENT_TRANSPORT=tcp
+PAYMENT_HOST=127.0.0.1
+PAYMENT_PORT=4003
+# PAYMENT_REDIS_URL=redis://localhost:6379
+# PAYMENT_NATS_URL=nats://localhost:4222
+
 # Per-request multipart file size cap (KB). Default 5120 (5 MB) when unset.
 MAX_FILE_SIZE_KB=5120

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/package.json

@@ -5,8 +5,8 @@
   "dependencies": {
     "@icore/auth-firebase": "*",
     "@icore/auth-supabase": "*",
+    "@icore/firebase-admin": "*",
     "@icore/shared": "*",
-    "firebase-admin": "^13.0.0",
     "@nestjs/common": "^11.1.24",
     "@nestjs/config": "^4.0.4",
     "@nestjs/core": "^11.1.24",

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": {