@idevconn/create-icore 0.4.1 → 0.5.1

package/dist/index.cjs

@@ -31,6 +31,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var src_exports = {};
 __export(src_exports, {
   collectOptions: () => collectOptions,
+  pmRun: () => pmRun,
   scaffold: () => scaffold
 });
 module.exports = __toCommonJS(src_exports);
@@ -39,6 +40,11 @@ module.exports = __toCommonJS(src_exports);
 var getImportMetaUrl = () => typeof document === "undefined" ? new URL(`file:${__filename}`).href : document.currentScript && document.currentScript.tagName.toUpperCase() === "SCRIPT" ? document.currentScript.src : new URL("main.js", document.baseURI).href;
 var importMetaUrl = /* @__PURE__ */ getImportMetaUrl();
 
+// src/lib/options.ts
+function pmRun(pm, script) {
+  return pm === "npm" ? `npm run ${script}` : `${pm} ${script}`;
+}
+
 // src/lib/scaffold.ts
 var import_promises = require("fs/promises");
 var import_node_fs = require("fs");
@@ -76,9 +82,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 (0, import_promises.writeFile)(pkgPath, JSON.stringify(pkg, null, 2) + "\n");
 }
 async function writeAuthEnv(targetDir, opts) {
@@ -116,9 +142,9 @@ async function writeNotesEnv(targetDir, opts) {
 async function writeGatewayEnv(targetDir, opts) {
   const envExample = (0, import_node_path.join)(targetDir, "apps/api/.env.example");
   const env = await (0, import_promises.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 (0, import_promises.writeFile)((0, import_node_path.join)(targetDir, "apps/api/.env"), next);
 }
@@ -131,6 +157,25 @@ async function writeRootEnv(targetDir, opts) {
   ];
   await (0, import_promises.writeFile)((0, import_node_path.join)(targetDir, ".env"), lines.join("\n"));
 }
+async function stripGatewayTransport(targetDir, prefix) {
+  const gatewayEnv = (0, import_node_path.join)(targetDir, "apps/api/.env");
+  try {
+    const env = await (0, import_promises.readFile)(gatewayEnv, "utf8");
+    const next = env.split("\n").filter(
+      (line) => !line.startsWith(`${prefix}_`) && !line.startsWith(`# ${prefix}_`) && !line.includes(`${prefix} MS transport`)
+    ).join("\n");
+    await (0, import_promises.writeFile)(gatewayEnv, next);
+  } catch {
+  }
+}
+async function writeClientEnv(targetDir) {
+  const envExample = (0, import_node_path.join)(targetDir, "apps/client/.env.example");
+  try {
+    const env = await (0, import_promises.readFile)(envExample, "utf8");
+    await (0, import_promises.writeFile)((0, import_node_path.join)(targetDir, "apps/client/.env"), env);
+  } catch {
+  }
+}
 async function writePaymentEnv(targetDir, opts) {
   if (opts.payment === "none") return;
   const envExample = (0, import_node_path.join)(targetDir, "apps/microservices/payment/.env.example");
@@ -207,6 +252,7 @@ async function removePaymentStack(targetDir) {
     "@icore/payment-client",
     "@idevconn/payment"
   ]);
+  await stripGatewayTransport(targetDir, "PAYMENT");
 }
 async function removeNotesStack(targetDir) {
   for (const p2 of [
@@ -228,6 +274,7 @@ async function removeNotesStack(targetDir) {
   } catch {
   }
   await stripDeps((0, import_node_path.join)(targetDir, "apps/api/package.json"), ["@icore/notes-client"]);
+  await stripGatewayTransport(targetDir, "NOTES");
   const tsconfigPath = (0, import_node_path.join)(targetDir, "tsconfig.base.json");
   try {
     const src = await (0, import_promises.readFile)(tsconfigPath, "utf8");
@@ -284,15 +331,17 @@ async function stripTsconfigPath(targetDir, alias) {
 }
 async function removeUnusedAuthStrategies(targetDir, authProvider) {
   const modulePath = (0, import_node_path.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 (0, import_promises.rm)((0, import_node_path.join)(targetDir, "libs/auth-strategies/firebase"), { recursive: true, force: true });
     await stripDeps((0, import_node_path.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 (0, import_promises.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 (0, import_promises.writeFile)(modulePath, next);
     } catch {
     }
@@ -305,10 +354,7 @@ async function removeUnusedAuthStrategies(targetDir, authProvider) {
     await stripTsconfigPath(targetDir, "@icore/auth-supabase");
     try {
       const src = await (0, import_promises.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 (0, import_promises.writeFile)(modulePath, next);
     } catch {
     }
@@ -320,7 +366,8 @@ async function removeUnusedStorageStrategies(targetDir, uploadProvider) {
   if (uploadProvider !== "firebase") {
     await (0, import_promises.rm)((0, import_node_path.join)(targetDir, "libs/storage-strategies/firebase"), { recursive: true, force: true });
     await stripDeps((0, import_node_path.join)(targetDir, "apps/microservices/upload/package.json"), [
-      "@icore/storage-firebase"
+      "@icore/storage-firebase",
+      "@icore/firebase-admin"
     ]);
     await stripTsconfigPath(targetDir, "@icore/storage-firebase");
   }
@@ -344,26 +391,26 @@ async function removeUnusedStorageStrategies(targetDir, uploadProvider) {
   try {
     let src = await (0, import_promises.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 (0, import_promises.writeFile)(modulePath, src);
   } catch {
   }
@@ -373,14 +420,15 @@ async function removeUnusedDbStrategies(targetDir, dbProvider) {
   if (dbProvider === "supabase") {
     await (0, import_promises.rm)((0, import_node_path.join)(targetDir, "libs/db-strategies/firestore"), { recursive: true, force: true });
     await stripDeps((0, import_node_path.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 (0, import_promises.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 (0, import_promises.writeFile)(modulePath, next);
     } catch {
@@ -394,15 +442,19 @@ async function removeUnusedDbStrategies(targetDir, dbProvider) {
     await stripTsconfigPath(targetDir, "@icore/db-supabase");
     try {
       const src = await (0, import_promises.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 (0, import_promises.writeFile)(modulePath, next);
     } catch {
     }
   }
 }
+async function removeFirebaseAdminLib(targetDir) {
+  await (0, import_promises.rm)((0, import_node_path.join)(targetDir, "libs/firebase-admin"), { recursive: true, force: true });
+  await stripTsconfigPath(targetDir, "@icore/firebase-admin");
+}
 async function removeUploadStack(targetDir) {
   const paths = [
     "apps/microservices/upload",
@@ -507,6 +559,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);
@@ -514,12 +567,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 (0, import_promises.writeFile)((0, import_node_path.join)(opts.targetDir, "yarn.lock"), "");
+  } else {
+    await (0, import_promises.rm)((0, import_node_path.join)(opts.targetDir, ".yarn"), { recursive: true, force: true });
+    await (0, import_promises.rm)((0, import_node_path.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 = (0, import_node_path.join)(targetDir, ".gitignore");
+  try {
+    let src = await (0, import_promises.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 (0, import_promises.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 (0, import_promises.writeFile)((0, import_node_path.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 (0, import_promises.writeFile)((0, import_node_path.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 (0, import_promises.writeFile)((0, import_node_path.join)(targetDir, "AGENTS.md"), agents);
+  await (0, import_promises.mkdir)((0, import_node_path.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 (0, import_promises.writeFile)(
+    (0, import_node_path.join)(targetDir, ".claude", "settings.json"),
+    JSON.stringify(settings, null, 2) + "\n"
+  );
+}
 
 // src/lib/prompts.ts
 var p = __toESM(require("@clack/prompts"), 1);
@@ -715,6 +986,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?`,
@@ -739,5 +1016,6 @@ Re-run with @latest to refresh:
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   collectOptions,
+  pmRun,
   scaffold
 });

package/dist/index.d.cts

@@ -7,6 +7,12 @@ type ExampleMode = 'notes' | 'none';
 type UiLibrary = 'shadcn' | 'antd' | 'mui';
 type MsTransport = 'tcp' | 'redis' | 'nats';
 type PackageManager = 'yarn' | 'npm' | 'pnpm';
+/**
+ * Returns the correct invocation for a package.json script.
+ * yarn/pnpm: `yarn <script>` / `pnpm <script>`
+ * npm:       `npm run <script>` (npm requires the `run` keyword for custom scripts)
+ */
+declare function pmRun(pm: PackageManager, script: string): string;
 interface CreateIcoreOptions {
     projectName: string;
     targetDir: string;
@@ -31,4 +37,4 @@ interface PromptInput {
 }
 declare function collectOptions({ argv, cwd }: PromptInput): Promise<CreateIcoreOptions>;
 
-export { type AuthProvider, type CreateIcoreOptions, type DbProvider, type ExampleMode, type JobsProvider, type MsTransport, type PackageManager, type PaymentProvider, type UiLibrary, type UploadProvider, collectOptions, scaffold };
+export { type AuthProvider, type CreateIcoreOptions, type DbProvider, type ExampleMode, type JobsProvider, type MsTransport, type PackageManager, type PaymentProvider, type UiLibrary, type UploadProvider, collectOptions, pmRun, scaffold };

package/dist/index.d.ts

@@ -7,6 +7,12 @@ type ExampleMode = 'notes' | 'none';
 type UiLibrary = 'shadcn' | 'antd' | 'mui';
 type MsTransport = 'tcp' | 'redis' | 'nats';
 type PackageManager = 'yarn' | 'npm' | 'pnpm';
+/**
+ * Returns the correct invocation for a package.json script.
+ * yarn/pnpm: `yarn <script>` / `pnpm <script>`
+ * npm:       `npm run <script>` (npm requires the `run` keyword for custom scripts)
+ */
+declare function pmRun(pm: PackageManager, script: string): string;
 interface CreateIcoreOptions {
     projectName: string;
     targetDir: string;
@@ -31,4 +37,4 @@ interface PromptInput {
 }
 declare function collectOptions({ argv, cwd }: PromptInput): Promise<CreateIcoreOptions>;
 
-export { type AuthProvider, type CreateIcoreOptions, type DbProvider, type ExampleMode, type JobsProvider, type MsTransport, type PackageManager, type PaymentProvider, type UiLibrary, type UploadProvider, collectOptions, scaffold };
+export { type AuthProvider, type CreateIcoreOptions, type DbProvider, type ExampleMode, type JobsProvider, type MsTransport, type PackageManager, type PaymentProvider, type UiLibrary, type UploadProvider, collectOptions, pmRun, scaffold };