@saasicat/cli 1.0.0-rc.0 → 1.0.0-rc.10

package/dist/index.js

@@ -909,7 +909,7 @@ var PlanCatalogDoctorCheck = class {
       severity: "ok",
       message: `${plans.length} plan(s), ${this.catalog.features?.length ?? 0} feature(s) loaded.`,
       details: {
-        projectKey: this.catalog.projectKey,
+        app: this.catalog.app.name,
         planIds: plans.map((p) => p.id)
       }
     };
@@ -1129,13 +1129,43 @@ function extractModelBlocks(fragment) {
   return extractBlocks(fragment, "model");
 }
 __name(extractModelBlocks, "extractModelBlocks");
+function extractEnumBlocks(fragment) {
+  return extractBlocks(fragment, "enum");
+}
+__name(extractEnumBlocks, "extractEnumBlocks");
+function extractEnumNames(schema2) {
+  return extractBlockNames(schema2, "enum");
+}
+__name(extractEnumNames, "extractEnumNames");
+function extractFragmentBlocks(fragment) {
+  return {
+    enums: extractEnumBlocks(fragment),
+    models: extractModelBlocks(fragment)
+  };
+}
+__name(extractFragmentBlocks, "extractFragmentBlocks");
 function applyFragmentBlocks(schema2, fragmentBlocks, options = {}) {
-  const existing = new Set(extractModelNames(schema2));
+  const blocks = fragmentBlocks instanceof Map ? {
+    enums: /* @__PURE__ */ new Map(),
+    models: fragmentBlocks
+  } : fragmentBlocks;
+  const existingModels = new Set(extractModelNames(schema2));
+  const existingEnums = new Set(extractEnumNames(schema2));
   const added = [];
   const skipped = [];
+  const addedEnums = [];
+  const skippedEnums = [];
   const additions = [];
-  for (const [name, block] of fragmentBlocks) {
-    if (existing.has(name)) {
+  for (const [name, block] of blocks.enums) {
+    if (existingEnums.has(name)) {
+      skippedEnums.push(name);
+    } else {
+      addedEnums.push(name);
+      additions.push(block);
+    }
+  }
+  for (const [name, block] of blocks.models) {
+    if (existingModels.has(name)) {
       skipped.push(name);
     } else {
       added.push(name);
@@ -1146,6 +1176,8 @@ function applyFragmentBlocks(schema2, fragmentBlocks, options = {}) {
     return {
       added,
       skipped,
+      addedEnums,
+      skippedEnums,
       schema: schema2
     };
   }
@@ -1162,6 +1194,8 @@ function applyFragmentBlocks(schema2, fragmentBlocks, options = {}) {
   return {
     added,
     skipped,
+    addedEnums,
+    skippedEnums,
     schema: trimmedSchema + header + additions.join("\n\n") + "\n"
   };
 }
@@ -1547,10 +1581,11 @@ function required(value, what) {
   return value;
 }
 __name(required, "required");
-function projectKeyPattern() {
-  return new RegExp(required(schema.properties?.projectKey?.pattern, "pattern for projectKey"));
+var APP_KEY_PATTERN = /^[a-z][a-z0-9-]{1,30}$/;
+function appKeyPattern() {
+  return APP_KEY_PATTERN;
 }
-__name(projectKeyPattern, "projectKeyPattern");
+__name(appKeyPattern, "appKeyPattern");
 function quotaKeyPattern() {
   const patterns = Object.keys(required(schema.$defs?.PlanDef?.properties?.quotas?.patternProperties, "quota key pattern"));
   if (patterns.length !== 1) {
@@ -1563,12 +1598,12 @@ function minimumQuotasPerPlan() {
   return required(schema.$defs?.PlanDef?.properties?.quotas?.minProperties, "minProperties");
 }
 __name(minimumQuotasPerPlan, "minimumQuotasPerPlan");
-function assertValidProjectKey(projectKey) {
-  const pattern = projectKeyPattern();
-  if (pattern.test(projectKey)) return;
-  throw new Error(`--project-key=${projectKey} is not a valid project key. It has to match ${pattern.source} \u2014 lower case, starting with a letter, at least two characters. The platform validates config/saas.yaml against the same pattern at boot, so this would fail after every file was written.`);
+function assertValidAppKey(appKey) {
+  const pattern = appKeyPattern();
+  if (pattern.test(appKey)) return;
+  throw new Error(`--app-key=${appKey} is not a valid app key. It has to match ${pattern.source} \u2014 lower case, starting with a letter, at least two characters. It becomes an npm package name and a browser storage prefix, so this would fail after every file was written.`);
 }
-__name(assertValidProjectKey, "assertValidProjectKey");
+__name(assertValidAppKey, "assertValidAppKey");
 function assertValidQuotaKey(quotaKey) {
   const pattern = quotaKeyPattern();
   if (pattern.test(quotaKey)) return;
@@ -1600,24 +1635,24 @@ function pascalCase(value) {
 __name(pascalCase, "pascalCase");
 var quotaFileName = /* @__PURE__ */ __name((key) => `${key.replace(/[^A-Za-z0-9]+/g, "-").toLowerCase()}-quota.provider.ts`, "quotaFileName");
 function planInit(options) {
-  const projectKey = options.projectKey;
-  if (!projectKey) throw new Error("init needs a --project-key.");
-  assertValidProjectKey(projectKey);
-  const appLabel = options.appName ?? pascalCase(projectKey);
+  const appKey = options.appKey;
+  if (!appKey) throw new Error("init needs an --app-key.");
+  assertValidAppKey(appKey);
+  const appLabel = options.appName ?? pascalCase(appKey);
   const appName = pascalCase(appLabel);
   const apiBase = options.apiBase ?? "/api/v1/admin";
   const quotas = (options.quotas ?? []).map(parseQuota);
   assertEnoughQuotas(quotas);
   const hasherClass = options.skipHasher ? null : `${appName}PasswordHasher`;
-  const featureKey = `${projectKey.replace(/[^A-Za-z0-9]+/g, "_").toUpperCase()}_CORE`;
+  const featureKey = `${appKey.replace(/[^A-Za-z0-9]+/g, "_").toUpperCase()}_CORE`;
   const shared = {
-    PROJECT_KEY: projectKey,
+    APP_KEY: appKey,
     APP_NAME: appName,
     APP_LABEL: appLabel,
     API_BASE: apiBase,
     FEATURE_KEY: featureKey,
-    REGISTRY_CONST: `${constantCase(projectKey)}_FEATURE_UI_REGISTRY`,
-    MANIFEST_CONST: `${constantCase(projectKey)}_MANIFEST_CONTRIBUTION`,
+    REGISTRY_CONST: `${constantCase(appKey)}_FEATURE_UI_REGISTRY`,
+    MANIFEST_CONST: `${constantCase(appKey)}_MANIFEST_CONTRIBUTION`,
     ADMIN_MODULE_CLASS: `${appName}AdminModule`,
     HASHER_CLASS: hasherClass ?? "",
     HASHER_FILE: hasherClass ? `${kebabCase(appName)}-password.hasher` : "",
@@ -1716,6 +1751,63 @@ function patchOptionsFor(plan) {
 }
 __name(patchOptionsFor, "patchOptionsFor");
 
+// src/init/module-resolution.ts
+import { join } from "path";
+var RESOLVES_SUBPATHS = /* @__PURE__ */ new Set([
+  "node16",
+  "nodenext",
+  "bundler"
+]);
+function judgeModuleResolution(value) {
+  if (value === null || RESOLVES_SUBPATHS.has(value)) {
+    return {
+      ok: true,
+      value
+    };
+  }
+  return {
+    ok: false,
+    value,
+    reason: `tsconfig.json resolves modules with "moduleResolution": "${value}"` + (value === "node10" ? ' (what TypeScript calls the "node" setting)' : "") + '. The files init writes import subpath exports (`@saasicat/nest/platform`, `/billing`, `/discovery`), which TypeScript resolves only under "node16", "nodenext" or "bundler". Set one of those first \u2014 `nest new` has used "nodenext" since NestJS 10.'
+  };
+}
+__name(judgeModuleResolution, "judgeModuleResolution");
+function readEffectiveModuleResolution(root, ts) {
+  const configPath = join(root, "tsconfig.json");
+  const read = ts.readConfigFile(configPath, ts.sys.readFile);
+  if (read.error || read.config === void 0) return null;
+  const parsed = ts.parseJsonConfigFileContent(read.config, ts.sys, root);
+  const kind = parsed.options.moduleResolution;
+  if (kind === void 0) return null;
+  return ts.ModuleResolutionKind[kind].toLowerCase();
+}
+__name(readEffectiveModuleResolution, "readEffectiveModuleResolution");
+
+// src/init/settings-written.ts
+import { loadPlanCatalogFromString } from "@saasicat/nest/billing";
+function flatten(prefix, value, into) {
+  if (value !== null && typeof value === "object" && !Array.isArray(value)) {
+    for (const [key, child] of Object.entries(value)) {
+      flatten(`${prefix}.${key}`, child, into);
+    }
+    return;
+  }
+  into.push({
+    key: prefix,
+    value: JSON.stringify(value)
+  });
+}
+__name(flatten, "flatten");
+function settingsWrittenTo(catalogYaml, source = "config/saas.yaml") {
+  const catalog = loadPlanCatalogFromString(catalogYaml, {
+    source
+  });
+  const settings = [];
+  flatten("tenantBilling", catalog.tenantBilling, settings);
+  return settings;
+}
+__name(settingsWrittenTo, "settingsWrittenTo");
+
 // src/codemods/v1-imports.ts
 var PUBLIC_PREFIXES = [
   "ui/",
@@ -1881,6 +1973,13 @@ function rewriteNames(text, table) {
       return `${quote}${to}`;
     });
   }
+  for (const [from, to] of Object.entries(table.packages ?? {})) {
+    if (from === "_") continue;
+    next = next.replace(new RegExp(`${escape(from)}(?=['"\`/])`, "g"), () => {
+      rewritten += 1;
+      return to;
+    });
+  }
   for (const [from, to] of Object.entries(table.subpaths)) {
     next = next.replace(new RegExp(escape(from), "g"), () => {
       rewritten += 1;
@@ -1896,6 +1995,402 @@ function rewriteNames(text, table) {
   };
 }
 __name(rewriteNames, "rewriteNames");
+var DEPENDENCY_FIELDS = [
+  "dependencies",
+  "devDependencies",
+  "peerDependencies",
+  "optionalDependencies"
+];
+var UNTRANSLATABLE_RANGE = /^(workspace:|file:|link:|npm:|git\+|https?:)/;
+function rewriteManifest(text, table, options) {
+  const renames = Object.entries(table.packages ?? {}).filter(([from]) => from !== "_");
+  const ambiguous = [];
+  let manifest;
+  try {
+    manifest = JSON.parse(text);
+  } catch {
+    return {
+      text,
+      rewritten: 0,
+      ambiguous
+    };
+  }
+  let rewritten = 0;
+  for (const field of DEPENDENCY_FIELDS) {
+    const deps = manifest[field];
+    if (!deps || typeof deps !== "object") continue;
+    const entries = Object.entries(deps);
+    const renamed = entries.map(([name, range]) => {
+      const to = renames.find(([from]) => from === name)?.[1];
+      if (!to) return [
+        name,
+        range
+      ];
+      if (UNTRANSLATABLE_RANGE.test(range)) {
+        ambiguous.push(`${name} in ${field} (${range})`);
+        return [
+          name,
+          range
+        ];
+      }
+      rewritten += 1;
+      return [
+        to,
+        options.targetRange
+      ];
+    });
+    manifest[field] = Object.fromEntries(renamed);
+  }
+  const meta = manifest.peerDependenciesMeta;
+  if (meta && typeof meta === "object") {
+    manifest.peerDependenciesMeta = Object.fromEntries(Object.entries(meta).map(([name, flags]) => {
+      const to = renames.find(([from]) => from === name)?.[1];
+      if (!to) return [
+        name,
+        flags
+      ];
+      rewritten += 1;
+      return [
+        to,
+        flags
+      ];
+    }));
+  }
+  if (rewritten === 0) return {
+    text,
+    rewritten: 0,
+    ambiguous
+  };
+  const indent = /^[ \t]+/m.exec(text)?.[0] ?? "    ";
+  const trailing = text.endsWith("\n") ? "\n" : "";
+  return {
+    text: JSON.stringify(manifest, null, indent) + trailing,
+    rewritten,
+    ambiguous
+  };
+}
+__name(rewriteManifest, "rewriteManifest");
+
+// src/codemods/v1-project-key.ts
+function stripQueryParameter(text) {
+  const NEEDLE = "projectKey=";
+  let out = "";
+  let index = 0;
+  const taken = /* @__PURE__ */ new Set();
+  for (; ; ) {
+    const at = text.indexOf(NEEDLE, index);
+    if (at < 0) break;
+    const separator = at === 0 ? "" : text[at - 1];
+    const value = separator === "?" || separator === "&" ? simpleValueEnd(text, at + NEEDLE.length) : null;
+    if (value === null || !servesTheCatalogue(text, at)) {
+      out += text.slice(index, at + NEEDLE.length);
+      index = at + NEEDLE.length;
+      continue;
+    }
+    out += text.slice(index, at - 1);
+    if (separator === "?" && text[value] === "&") {
+      out += "?";
+      index = value + 1;
+    } else {
+      index = value;
+    }
+    taken.add(at);
+  }
+  return {
+    text: out + text.slice(index),
+    taken
+  };
+}
+__name(stripQueryParameter, "stripQueryParameter");
+var HIDES_A_BRACE = /[`'"{}/\\]/;
+function simpleValueEnd(text, from) {
+  let i = from;
+  while (i < text.length) {
+    const ch = text[i];
+    if (ch === "&" || ch === "#" || ch === "'" || ch === '"' || ch === "`" || ch === "\n" || ch === " ") {
+      return i;
+    }
+    if (ch !== "$" || text[i + 1] !== "{") {
+      if (ch === "{" || ch === "}") return null;
+      i += 1;
+      continue;
+    }
+    const close = text.indexOf("}", i + 2);
+    if (close < 0) return null;
+    if (HIDES_A_BRACE.test(text.slice(i + 2, close))) return null;
+    i = close + 1;
+  }
+  return null;
+}
+__name(simpleValueEnd, "simpleValueEnd");
+function servesTheCatalogue(text, at) {
+  let start = at;
+  while (start > 0) {
+    const ch = text[start - 1];
+    if (ch === "`" || ch === "'" || ch === '"' || ch === "\n") break;
+    start -= 1;
+  }
+  const url = text.slice(start, at);
+  const query = url.indexOf("?");
+  return (query < 0 ? url : url.slice(0, query)).includes("/catalog/");
+}
+__name(servesTheCatalogue, "servesTheCatalogue");
+function isIdentifierChar(ch) {
+  return ch !== void 0 && /[A-Za-z0-9_$]/.test(ch);
+}
+__name(isIdentifierChar, "isIdentifierChar");
+function lineAt(text, at) {
+  let line = 1;
+  for (let i = 0; i < at; i += 1) if (text[i] === "\n") line += 1;
+  return line;
+}
+__name(lineAt, "lineAt");
+function removeProjectKey(text, kind = "source") {
+  if (kind === "yaml") return removeFromYaml(text);
+  const query = stripQueryParameter(text);
+  const reported = /* @__PURE__ */ new Set();
+  for (let at = text.indexOf("projectKey"); at >= 0; at = text.indexOf("projectKey", at + 1)) {
+    if (query.taken.has(at)) continue;
+    if (isIdentifierChar(text[at - 1])) continue;
+    if (isIdentifierChar(text[at + "projectKey".length])) continue;
+    reported.add(lineAt(text, at));
+  }
+  return {
+    text: query.text,
+    rewritten: query.taken.size,
+    undecided: [
+      ...reported
+    ].sort((a, b) => a - b)
+  };
+}
+__name(removeProjectKey, "removeProjectKey");
+function removeFromYaml(text) {
+  const lines = text.split("\n");
+  const kept = [];
+  let rewritten = 0;
+  for (const line of lines) {
+    if (line.startsWith("projectKey:")) {
+      rewritten += 1;
+      continue;
+    }
+    kept.push(line);
+  }
+  return {
+    text: kept.join("\n"),
+    rewritten,
+    undecided: []
+  };
+}
+__name(removeFromYaml, "removeFromYaml");
+
+// src/codemods/v1-moved-settings.ts
+import { planCatalogSchema as planCatalogSchema2 } from "@saasicat/spec";
+var SETTINGS_THAT_MOVED = Object.keys(planCatalogSchema2.properties?.tenantBilling?.properties ?? (() => {
+  throw new Error("plan-catalog.schema.json declares no tenantBilling properties \u2014 @saasicat/spec and @saasicat/cli are out of step.");
+})());
+var isIdentifierChar2 = /* @__PURE__ */ __name((ch) => ch !== void 0 && /[A-Za-z0-9_$]/.test(ch), "isIdentifierChar");
+function lineAt2(text, index) {
+  let line = 1;
+  for (let at = 0; at < index; at += 1) {
+    if (text[at] === "\n") line += 1;
+  }
+  return line;
+}
+__name(lineAt2, "lineAt");
+var SCANNED_FOR_MOVED_SETTINGS = /\.(ts|tsx|mts|cts|js|jsx|mjs|cjs|vue)$/;
+function findMovedSettings(text) {
+  const occurrences = [];
+  for (const setting of SETTINGS_THAT_MOVED) {
+    for (let at = text.indexOf(setting); at >= 0; at = text.indexOf(setting, at + 1)) {
+      if (isIdentifierChar2(text[at - 1])) continue;
+      if (isIdentifierChar2(text[at + setting.length])) continue;
+      occurrences.push({
+        setting,
+        line: lineAt2(text, at)
+      });
+    }
+  }
+  return {
+    occurrences: occurrences.sort((a, b) => a.line - b.line || a.setting.localeCompare(b.setting))
+  };
+}
+__name(findMovedSettings, "findMovedSettings");
+var WHERE_IT_GOES = {
+  cancellationNoticeDays: "config/saas.yaml \u2192 tenantBilling.cancellationNoticeDays \u2014 both `monthly` and `yearly` are required, so write the number you are running today rather than leaving one out.",
+  selfServiceBlockedPlans: 'config/saas.yaml \u2192 tenantBilling.selfServiceBlockedPlans \u2014 both `asTarget` and `asSource` are required, and `[]` is the way to say "nothing is blocked".'
+};
+
+// src/codemods/v1-db-catalog.ts
+import { DB_CATALOG_MEMBERS } from "@saasicat/nest/platform";
+var SCANNED_FOR_DB_CATALOG = SCANNED_FOR_MOVED_SETTINGS;
+var PROPERTY = "dbCatalog";
+var TAKEN = new Set(DB_CATALOG_MEMBERS);
+var isIdentifierStart = /* @__PURE__ */ __name((ch) => ch !== void 0 && /[A-Za-z_$]/.test(ch), "isIdentifierStart");
+var isIdentifierChar3 = /* @__PURE__ */ __name((ch) => ch !== void 0 && /[A-Za-z0-9_$]/.test(ch), "isIdentifierChar");
+var isBlank = /* @__PURE__ */ __name((ch) => ch === " " || ch === "	" || ch === "\n" || ch === "\r", "isBlank");
+function lineAt3(text, index) {
+  let line = 1;
+  for (let at = 0; at < index; at += 1) {
+    if (text[at] === "\n") line += 1;
+  }
+  return line;
+}
+__name(lineAt3, "lineAt");
+function skipBlanks(text, from) {
+  let at = from;
+  while (isBlank(text[at])) at += 1;
+  return at;
+}
+__name(skipBlanks, "skipBlanks");
+function closingQuote(text, open) {
+  const quote = text[open];
+  for (let at = open + 1; at < text.length; at += 1) {
+    if (text[at] === "\\") {
+      at += 1;
+      continue;
+    }
+    if (text[at] === quote) return at;
+  }
+  return text.length;
+}
+__name(closingQuote, "closingQuote");
+function skipCommentOrString(text, at) {
+  const ch = text[at];
+  if (ch === "/" && text[at + 1] === "/") {
+    const end = text.indexOf("\n", at);
+    return end === -1 ? text.length : end;
+  }
+  if (ch === "/" && text[at + 1] === "*") {
+    const end = text.indexOf("*/", at + 2);
+    return end === -1 ? text.length : end + 2;
+  }
+  if (ch === "'" || ch === '"' || ch === "`") return closingQuote(text, at) + 1;
+  return at;
+}
+__name(skipCommentOrString, "skipCommentOrString");
+function objectLiteralAt(text, open) {
+  const members = [];
+  let depth = 0;
+  let expectingKey = true;
+  let at = open + 1;
+  while (at < text.length) {
+    const ch = text[at];
+    if (ch === "'" || ch === '"' || ch === "`") {
+      const end = closingQuote(text, at);
+      if (depth === 0 && expectingKey && text[skipBlanks(text, end + 1)] === ":") {
+        members.push(text.slice(at + 1, end));
+      }
+      at = end + 1;
+      continue;
+    }
+    const skipped = skipCommentOrString(text, at);
+    if (skipped > at) {
+      at = skipped;
+      continue;
+    }
+    if (ch === "{" || ch === "[" || ch === "(") {
+      depth += 1;
+      at += 1;
+      continue;
+    }
+    if (ch === "}" || ch === "]" || ch === ")") {
+      if (depth === 0) return {
+        members,
+        end: at + 1
+      };
+      depth -= 1;
+      at += 1;
+      continue;
+    }
+    if (depth === 0 && ch === ":") expectingKey = false;
+    if (depth === 0 && ch === ",") expectingKey = true;
+    if (depth === 0 && expectingKey && ch === "." && text.startsWith("...", at)) {
+      let end = at + 3;
+      while (isIdentifierChar3(text[end])) end += 1;
+      members.push(text.slice(at, end));
+      at = end;
+      continue;
+    }
+    if (depth === 0 && expectingKey && isIdentifierStart(ch)) {
+      let end = at;
+      while (isIdentifierChar3(text[end])) end += 1;
+      const next = text[skipBlanks(text, end)];
+      if (next === ":" || next === "," || next === "}") members.push(text.slice(at, end));
+      at = end;
+      continue;
+    }
+    at += 1;
+  }
+  return {
+    members,
+    end: text.length
+  };
+}
+__name(objectLiteralAt, "objectLiteralAt");
+function findDbCatalogBlocks(text) {
+  const occurrences = [];
+  let at = 0;
+  while (at < text.length) {
+    const skipped = skipCommentOrString(text, at);
+    if (skipped > at) {
+      at = skipped;
+      continue;
+    }
+    if (!text.startsWith(PROPERTY, at) || isIdentifierChar3(text[at - 1])) {
+      at += 1;
+      continue;
+    }
+    const afterName = at + PROPERTY.length;
+    if (isIdentifierChar3(text[afterName])) {
+      at = afterName;
+      continue;
+    }
+    const colon = skipBlanks(text, afterName);
+    if (text[colon] !== ":") {
+      at = afterName;
+      continue;
+    }
+    const value = skipBlanks(text, colon + 1);
+    const line = lineAt3(text, at);
+    if (text[value] !== "{") {
+      occurrences.push({
+        line,
+        shape: "reference",
+        leftovers: []
+      });
+      at = value;
+      continue;
+    }
+    const { members, end } = objectLiteralAt(text, value);
+    const leftovers = members.filter((member) => !TAKEN.has(member));
+    if (!members.includes("path")) {
+      occurrences.push({
+        line,
+        shape: "values",
+        leftovers
+      });
+    } else if (leftovers.length > 0) {
+      occurrences.push({
+        line,
+        shape: "mixed",
+        leftovers
+      });
+    }
+    at = end;
+  }
+  return {
+    occurrences
+  };
+}
+__name(findDbCatalogBlocks, "findDbCatalogBlocks");
+function describeDbCatalogOccurrence(occurrence) {
+  const { shape, leftovers } = occurrence;
+  if (shape === "reference") return "carries something this cannot see into";
+  if (shape === "mixed") return `names the path but still carries ${leftovers.join(", ")}`;
+  return leftovers.length > 0 ? `carries the values: ${leftovers.join(", ")}` : "names no path";
+}
+__name(describeDbCatalogOccurrence, "describeDbCatalogOccurrence");
+var WHERE_DB_CATALOG_GOES = "dbCatalog: { path: 'config/saas.yaml' } \u2014 the file the values were forwarded from. Delete the values; the platform reads app, currency, vatRate, tenantBilling, marketing and notifications from the file it names, and the plans from the read sink as before.";
 
 // src/init/patch-app-module.ts
 var MARKER = "SaaSiCatModule.forRoot";
@@ -1917,7 +2412,7 @@ ${block}`;
     return {
       source,
       status: "declined",
-      reason: "no `@Module({ imports: [ ... ] })` was found in this file, so there is nowhere to add the platform without guessing at the structure",
+      reason: "this file has no `@Module({ ... })` with an `imports:` key on a line of its own \u2014 the shape `nest new` writes \u2014 so there is nowhere to add the platform without guessing at the structure",
       manualBlock
     };
   }
@@ -1996,7 +2491,7 @@ function renderForRootBlock(options) {
     "SaaSiCatModule.forRoot(",
     "    defineSaaSiCat({",
     "        // Plans straight from the YAML. Apps that manage plans in the",
-    "        // SuperAdmin UI pass `dbCatalog` instead.",
+    "        // SuperAdmin UI pass `dbCatalog: { path: 'config/saas.yaml' }` instead.",
     "        planCatalog: loadPlanCatalogFromFile({ path: 'config/saas.yaml' }),",
     "        // Your authentication guard. This does NOT compile until you",
     "        // name one, and that is deliberate: an empty array is how the",
@@ -2005,6 +2500,13 @@ function renderForRootBlock(options) {
     "        // your whole capability inventory \u2014 and the manifest routes to",
     "        // anyone who asks. Import your guard and put it in.",
     "        controller: { guards: [YourAuthGuard] },",
+    "        // The modules whose providers the platform injects: the one",
+    "        // exporting PrismaService, and the one your guard depends on.",
+    "        // `prismaPersistence({ client: PrismaService })` is resolved",
+    "        // inside the platform module, which sees only what is listed",
+    "        // here or declared @Global. Same rule as the guard: this does",
+    "        // not compile until you name them.",
+    "        imports: [YourPrismaModule, YourAuthModule],",
     options.persistenceImport ? "        persistence," : "        // persistence: prismaPersistence({ client: PrismaService }),",
     "        catalog: { featureUiRegistry: " + options.registry.constName + " },",
     "        adminResources: true,",
@@ -3106,17 +3608,23 @@ export {
   MfaSetupFlow,
   PLATFORM_DOCTOR_CHECK_PROVIDERS,
   PlanCatalogDoctorCheck,
+  SCANNED_FOR_DB_CATALOG,
+  SCANNED_FOR_MOVED_SETTINGS,
+  SETTINGS_THAT_MOVED,
   UI_VUE_SPECIFIER,
   USER_MANAGEMENT_PORT_TOKEN,
   USER_PORT_TOKEN,
   UserCommands,
   UserPortDoctorCheck,
+  WHERE_DB_CATALOG_GOES,
+  WHERE_IT_GOES,
   WhoAmIFlow,
+  appKeyPattern,
   appendConstraints,
   applyFragmentBlocks,
   applyTokens,
   assertModelsExist,
-  assertValidProjectKey,
+  assertValidAppKey,
   assertValidQuotaKey,
   blankStringLiterals,
   blockBodyLines,
@@ -3124,17 +3632,24 @@ export {
   buildImportMap,
   checkSchema,
   constraintsFor,
+  describeDbCatalogOccurrence,
   enableFkPointers,
   extractBlockNames,
   extractBlocks,
+  extractEnumBlocks,
+  extractEnumNames,
+  extractFragmentBlocks,
   extractModelBlocks,
   extractModelNames,
+  findDbCatalogBlocks,
   findFkPointers,
+  findMovedSettings,
   foreignKeyOf,
   hasBackRelation,
   hasConstraints,
   isNoLongerPublic,
   isOneToOne,
+  judgeModuleResolution,
   kebabCase,
   migrationCreatedBy,
   minimumQuotasPerPlan,
@@ -3148,13 +3663,16 @@ export {
   patchAppModule,
   patchOptionsFor,
   planInit,
-  projectKeyPattern,
   quotaKeyPattern,
+  readEffectiveModuleResolution,
   relationNameOf,
+  removeProjectKey,
   reportConstraints,
   rewriteImports,
+  rewriteManifest,
   rewriteNames,
   rewriteSubpath,
+  settingsWrittenTo,
   stripLineComment,
   structuralOnly,
   tablesAddressedBy