@saasicat/cli 1.0.0-rc.7 → 1.0.0-rc.9

package/README.md

@@ -46,6 +46,14 @@ import { PrismaUserPortAdapter } from './adapters/prisma-user-port';
             app: { name: 'MyApp' },
             currency: 'EUR',
             vatRate: 19,
+            // Spelled out here like the three above it. In an application
+            // these come from `loadPlanCatalogFromFile('config/saas.yaml')` —
+            // the settings are never in the database, so the file is the only
+            // place they can come from.
+            tenantBilling: {
+                cancellationNoticeDays: { monthly: 0, yearly: 0 },
+                selfServiceBlockedPlans: { asTarget: [], asSource: [] },
+            },
             // The catalogue is read from the database, not from a file — the
             // CLI's `plan-catalog import` puts it there.
             sink: {

package/bin/saasicat.js

@@ -21,7 +21,8 @@
 //   codemod v1-imports [--dir=X] [--dry-run]
 //   codemod v1-rename  [--dir=X] [--dry-run]
 //   codemod v1-project-key [--dir=X] [--dry-run]
-//   codemod v1         [--dir=X] [--dry-run]   — all three, in that order
+//   codemod v1-moved-settings [--dir=X]
+//   codemod v1         [--dir=X] [--dry-run]   — all four, in that order
 //        [--skip-hasher] [--dry-run] [--dir=.]
 //       Writes the platform wiring — config, persistence, manifest
 //       contribution, admin module, one provider per quota — and adds
@@ -61,6 +62,10 @@ import {
     patchAppModule,
     patchOptionsFor,
     planInit,
+    settingsWrittenTo,
+    findMovedSettings,
+    SCANNED_FOR_MOVED_SETTINGS,
+    WHERE_IT_GOES,
 } from '../dist/index.js';
 
 const require_ = createRequire(import.meta.url);
@@ -736,6 +741,51 @@ async function walkSources(root, visit, extra = null) {
  * TypeScript, so removing one would sometimes delete a member of the consumer's
  * own type. The migration guide's table says what each shape becomes.
  */
+/**
+ * Names the module options that moved into `config/saas.yaml`.
+ *
+ * Read-only on purpose — see `codemods/v1-moved-settings.ts` for why removing
+ * them would lose the decision instead of moving it. `--dry-run` is accepted
+ * and does nothing, so `codemod v1 --dry-run` behaves the same throughout.
+ */
+async function cmdCodemodV1MovedSettings(args) {
+    const root = resolve(args.dir ?? '.');
+    const found = [];
+
+    await walkSources(root, async (full, source) => {
+        // Code only. The walk includes Markdown, and a documentation file that
+        // mentions a setting is not a file that passes one — see
+        // `SCANNED_FOR_MOVED_SETTINGS`.
+        if (!SCANNED_FOR_MOVED_SETTINGS.test(full)) return;
+        for (const { setting, line } of findMovedSettings(source).occurrences) {
+            found.push({ where: `${relative(root, full)}:${line}`, setting });
+        }
+    });
+
+    if (found.length === 0) {
+        console.log('No module option that moved into config/saas.yaml is still passed.');
+        return;
+    }
+
+    console.log(`${found.length} occurrence(s) of a setting that moved:`);
+    const width = Math.max(...found.map((f) => f.where.length));
+    for (const { where, setting } of found) {
+        console.log(`  ${where.padEnd(width)}  ${setting}`);
+    }
+    console.log('');
+    console.log('  Not removed, and that is the point: the value is a term somebody agreed,');
+    console.log('  and deleting it here without writing it into the file would leave the');
+    console.log('  application running on whatever the file happens to say. Move each one:');
+    console.log('');
+    for (const setting of new Set(found.map((f) => f.setting))) {
+        console.log(`  ${setting}`);
+        console.log(`      ${WHERE_IT_GOES[setting]}`);
+    }
+    console.log('');
+    console.log('  TenantBillingModule.forRoot() refuses to boot while either is still');
+    console.log('  passed, so this cannot be half-done quietly.');
+}
+
 async function cmdCodemodV1ProjectKey(args) {
     const root = resolve(args.dir ?? '.');
     const dryRun = args['dry-run'] === true;
@@ -874,6 +924,8 @@ async function cmdInit(args, argv) {
         for (const w of writes) console.log(`    ${w.path}`);
     }
 
+    reportSettings(writes, root);
+
     await patchAppModuleFile(root, plan, args);
 
     console.log('');
@@ -895,6 +947,33 @@ async function cmdInit(args, argv) {
     }
 }
 
+/**
+ * Says which settings the catalogue now carries, with their values and its path.
+ *
+ * These are required fields without defaults, and there is no second place they
+ * can come from. Somebody who has just run `init` should not have to find that
+ * out from a boot failure six weeks later — so the command names the file it
+ * put them in while they are still looking at the output.
+ *
+ * Derived in `init/settings-written.ts`, where it can be tested: this file is
+ * not.
+ */
+function reportSettings(writes, root) {
+    const catalog = writes.find((w) => w.path === 'config/saas.yaml');
+    if (!catalog) return;
+    const settings = settingsWrittenTo(catalog.content, catalog.path);
+    if (settings.length === 0) return;
+
+    const width = Math.max(...settings.map((s) => s.key.length));
+    console.log('');
+    console.log(`Settings written to ${join(root, catalog.path)}:`);
+    for (const { key, value } of settings) {
+        console.log(`    ${key.padEnd(width)}  ${value}`);
+    }
+    console.log('  This file is where they live. Editing it is how they change, and the');
+    console.log('  change lands on the next restart — the platform reads it at boot.');
+}
+
 /**
  * The TypeScript that will compile the project: the consumer's own, resolved
  * from the project root, so the tsconfig is read the way the build reads it.
@@ -965,12 +1044,16 @@ async function main() {
     if (cmd === 'codemod' && sub === 'v1-project-key') {
         return cmdCodemodV1ProjectKey(parseArgs(rest));
     }
+    if (cmd === 'codemod' && sub === 'v1-moved-settings') {
+        return cmdCodemodV1MovedSettings(parseArgs(rest));
+    }
     if (cmd === 'codemod' && sub === 'v1') {
         // Imports first: the rename table keys its per-entry tokens by the
         // specifier they are imported from, which the import rewrite settles.
         await cmdCodemodV1Imports(parseArgs(rest));
         await cmdCodemodV1Rename(parseArgs(rest));
-        return cmdCodemodV1ProjectKey(parseArgs(rest));
+        await cmdCodemodV1ProjectKey(parseArgs(rest));
+        return cmdCodemodV1MovedSettings(parseArgs(rest));
     }
     if (cmd === 'init') {
         return cmdInit(parseArgs([sub, ...rest].filter(Boolean)), process.argv.slice(3));
@@ -1005,12 +1088,17 @@ async function main() {
         console.log('  init --app-key=myapp --quota=notes:Note --quota=seats:Seat');
         console.log('');
         console.log('  codemod v1 [--dir=.] [--dry-run]');
-        console.log('          the whole 1.0 migration: imports, names, then projectKey');
+        console.log('          the whole 1.0 migration: imports, names, projectKey, then the');
+        console.log('          settings that moved into config/saas.yaml');
         console.log('  codemod v1-imports [--dir=.] [--dry-run]');
         console.log('          rewrite @saasicat/ui-vue imports to the 1.0 export map');
         console.log('  codemod v1-rename [--dir=.] [--dry-run]');
         console.log('          rewrite the names 1.0 changed: SaasPlatform*, Symbol.for keys,');
         console.log('          FEATURE_UI_REGISTRY_TOKEN, @saasicat/ui-vue/testing-e2e/*');
+        console.log('  codemod v1-moved-settings [--dir=.]');
+        console.log('          name the module options that moved into config/saas.yaml.');
+        console.log('          Reports only — the value is a commercial decision, and this');
+        console.log('          would delete it without writing it anywhere.');
         console.log('');
         console.log('Optional --prisma-schema=PATH (default prisma/schema.prisma).');
         console.log('Optional --tenant-model=X --user-model=Y for apply/migrate — enables');

package/dist/.build-stamp

@@ -1 +1 @@
-e08122ad3833db9d96fed2edad527604182ab8047a8d8afefec4239ec29fe8f8
+d41946fb8c4579edeeaf5f0199b97a2a41d75f2fcf92a77674e97622ff72f631

package/dist/index.cjs

@@ -64,11 +64,14 @@ __export(index_exports, {
   MfaSetupFlow: () => MfaSetupFlow,
   PLATFORM_DOCTOR_CHECK_PROVIDERS: () => PLATFORM_DOCTOR_CHECK_PROVIDERS,
   PlanCatalogDoctorCheck: () => PlanCatalogDoctorCheck,
+  SCANNED_FOR_MOVED_SETTINGS: () => SCANNED_FOR_MOVED_SETTINGS,
+  SETTINGS_THAT_MOVED: () => SETTINGS_THAT_MOVED,
   UI_VUE_SPECIFIER: () => UI_VUE_SPECIFIER,
   USER_MANAGEMENT_PORT_TOKEN: () => USER_MANAGEMENT_PORT_TOKEN,
   USER_PORT_TOKEN: () => USER_PORT_TOKEN,
   UserCommands: () => UserCommands,
   UserPortDoctorCheck: () => UserPortDoctorCheck,
+  WHERE_IT_GOES: () => WHERE_IT_GOES,
   WhoAmIFlow: () => WhoAmIFlow,
   appKeyPattern: () => appKeyPattern,
   appendConstraints: () => appendConstraints,
@@ -92,6 +95,7 @@ __export(index_exports, {
   extractModelBlocks: () => extractModelBlocks,
   extractModelNames: () => extractModelNames,
   findFkPointers: () => findFkPointers,
+  findMovedSettings: () => findMovedSettings,
   foreignKeyOf: () => foreignKeyOf,
   hasBackRelation: () => hasBackRelation,
   hasConstraints: () => hasConstraints,
@@ -120,6 +124,7 @@ __export(index_exports, {
   rewriteManifest: () => rewriteManifest,
   rewriteNames: () => rewriteNames,
   rewriteSubpath: () => rewriteSubpath,
+  settingsWrittenTo: () => settingsWrittenTo,
   stripLineComment: () => stripLineComment,
   structuralOnly: () => structuralOnly,
   tablesAddressedBy: () => tablesAddressedBy
@@ -1908,6 +1913,31 @@ function readEffectiveModuleResolution(root, ts) {
 }
 __name(readEffectiveModuleResolution, "readEffectiveModuleResolution");
 
+// src/init/settings-written.ts
+var import_billing = require("@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 = (0, import_billing.loadPlanCatalogFromString)(catalogYaml, {
+    source
+  });
+  const settings = [];
+  flatten("tenantBilling", catalog.tenantBilling, settings);
+  return settings;
+}
+__name(settingsWrittenTo, "settingsWrittenTo");
+
 // src/codemods/v1-imports.ts
 var PUBLIC_PREFIXES = [
   "ui/",
@@ -2283,6 +2313,43 @@ function removeFromYaml(text) {
 }
 __name(removeFromYaml, "removeFromYaml");
 
+// src/codemods/v1-moved-settings.ts
+var import_spec2 = require("@saasicat/spec");
+var SETTINGS_THAT_MOVED = Object.keys(import_spec2.planCatalogSchema.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/init/patch-app-module.ts
 var MARKER = "SaaSiCatModule.forRoot";
 function patchAppModule(source, options) {
@@ -3500,11 +3567,14 @@ UserCommands = _ts_decorate14([
   MfaSetupFlow,
   PLATFORM_DOCTOR_CHECK_PROVIDERS,
   PlanCatalogDoctorCheck,
+  SCANNED_FOR_MOVED_SETTINGS,
+  SETTINGS_THAT_MOVED,
   UI_VUE_SPECIFIER,
   USER_MANAGEMENT_PORT_TOKEN,
   USER_PORT_TOKEN,
   UserCommands,
   UserPortDoctorCheck,
+  WHERE_IT_GOES,
   WhoAmIFlow,
   appKeyPattern,
   appendConstraints,
@@ -3528,6 +3598,7 @@ UserCommands = _ts_decorate14([
   extractModelBlocks,
   extractModelNames,
   findFkPointers,
+  findMovedSettings,
   foreignKeyOf,
   hasBackRelation,
   hasConstraints,
@@ -3556,6 +3627,7 @@ UserCommands = _ts_decorate14([
   rewriteManifest,
   rewriteNames,
   rewriteSubpath,
+  settingsWrittenTo,
   stripLineComment,
   structuralOnly,
   tablesAddressedBy

package/dist/index.d.cts

@@ -869,6 +869,21 @@ declare function assertValidAppKey(appKey: string): void;
 /** The same, for a quota key. `additionalProperties: false` makes it a hard rule. */
 declare function assertValidQuotaKey(quotaKey: string): void;
 
+interface WrittenSetting {
+    /** Dotted path as it reads in the file, e.g. `tenantBilling.cancellationNoticeDays.monthly`. */
+    key: string;
+    /** The value as JSON — `0`, `[]`, `"EUR"` — so an empty list is visible as one. */
+    value: string;
+}
+/**
+ * The settings a generated `config/saas.yaml` carries.
+ *
+ * Loaded with the platform's own loader, not a YAML parse: a document `init`
+ * writes that the platform would refuse is a bug worth failing the generation
+ * for, rather than one the first boot reports after every file exists.
+ */
+declare function settingsWrittenTo(catalogYaml: string, source?: string): WrittenSetting[];
+
 /** One entry of the move table: where a file was, and where it went. */
 interface MoveTable {
     readonly moves: Readonly<Record<string, string>>;
@@ -1000,6 +1015,65 @@ interface ProjectKeyResult {
  */
 declare function removeProjectKey(text: string, kind?: 'source' | 'yaml'): ProjectKeyResult;
 
+/**
+ * The settings that belong in `config/saas.yaml#tenantBilling`, read off the
+ * schema that defines them.
+ *
+ * Not a list here, and not a copy of the one in `@saasicat/nest`: both derive
+ * from the same schema, so the day a third setting moves into that block, this
+ * codemod names it and the module refuses it without either being edited.
+ */
+declare const SETTINGS_THAT_MOVED: readonly string[];
+type MovedSetting = string;
+interface MovedSettingOccurrence {
+    /** Which setting it is, so the report can say where it goes. */
+    readonly setting: MovedSetting;
+    /** 1-based line number. */
+    readonly line: number;
+}
+interface MovedSettingsResult {
+    readonly occurrences: readonly MovedSettingOccurrence[];
+}
+/**
+ * Files a moved setting can actually be passed in.
+ *
+ * The codemod walk includes Markdown, and both consumers keep large
+ * documentation folders — an upgrade note that mentions `cancellationNoticeDays`
+ * would land in the report beside the line somebody has to change, and a report
+ * that mixes the two is one nobody reads twice. Prose cannot pass a module
+ * option, so prose is not scanned.
+ */
+declare const SCANNED_FOR_MOVED_SETTINGS: RegExp;
+/**
+ * Every occurrence of a moved setting in one source file.
+ *
+ * Matched on word boundaries alone: a longer name that contains it
+ * (`cancellationNoticeDaysV2`) is not reported, and everything else is —
+ * including a mention in a comment or a string.
+ *
+ * That last part is deliberate, and it is the opposite trade from the one this
+ * comment used to claim. Requiring a colon would read as "only a property",
+ * and it would then miss `{ cancellationNoticeDays }` and
+ * `const { cancellationNoticeDays } = options` — two ordinary ways to pass the
+ * same option. Telling a comment from code needs the grammar, which this does
+ * not have. So it over-reports inside code, where the cost is a glance, rather
+ * than under-reporting, where the cost is somebody not learning that their
+ * value is about to stop being read.
+ *
+ * A property access (`config.cancellationNoticeDays`) is reported too: reading
+ * the value back from module options is the same migration, one step further
+ * along.
+ */
+declare function findMovedSettings(text: string): MovedSettingsResult;
+/**
+ * Where a setting goes, for the report.
+ *
+ * One sentence per setting rather than one for both: they end up in the same
+ * block and mean different things, and "move these two to the file" is the
+ * instruction people follow halfway.
+ */
+declare const WHERE_IT_GOES: Record<string, string>;
+
 interface PatchAppModuleOptions {
     /** Import specifier for the persistence bundle, or null when not generated. */
     persistenceImport: string | null;
@@ -1243,4 +1317,4 @@ declare class UserCommands extends CommandRunner {
     parsePassword(val: string): string;
 }
 
-export { AUDIT_QUERY_PORT_TOKEN, AdminCommands, AdminManifestDoctorCheck, AdminMfaSetupCommand, AdminWhoamiCommand, type ApplyResult, AuditCommands, AuditTailCommand, AuditTailFlow, type AuditTailOptions, type BlockAttributeKind, type BlockAttributes, CLI_CONTEXT_CONFIG_TOKEN, CONSTRAINTS_MARKER, type CheckSeverity, type CliContextConfig, CliContextModule, type CliContextModuleOptions, CliContextService, CliError, type CliIdentity, type ConstraintsOutcome, type ConstraintsReport, DEFAULT_MANIFEST_CHECKS, DOCTOR_CHECKS_TOKEN, DiscoveryCommands, DiscoveryScanCommand, DiscoverySnapshotDoctorCheck, type DoctorCheck, type DoctorCheckResult, DoctorCommands, DoctorFlow, type DoctorReport, type EnableFkResult, type FieldMismatch, type FieldMismatchReason, type FieldSignature, type FkModelNames, type FkPointer, type FragmentBlocks, type InitOptions, type InitPlan, LIMIT_FILTER_IMPORTS, LIMIT_FILTER_PROVIDER, MANIFEST_ACCESS_PORT_TOKEN, MANIFEST_CHECKS_TOKEN, type ManifestCheck, ManifestCheckCommand, type ManifestCheckReport, type ManifestCheckResult, ManifestCliFlow, ManifestCommands, type ManifestDiff, ManifestDumpCommand, ManifestHashCommand, type ManifestRewriteOptions, ManifestValidateCommand, MfaSetupFlow, type MfaSetupOptions, type MfaSetupResult, type MissingBlockAttribute, type MissingEnumValue, type MissingField, type ModuleResolutionVerdict, type MoveTable, PLATFORM_DOCTOR_CHECK_PROVIDERS, type ParsedSchema, type PatchAppModuleOptions, type PatchOptionsFromPlan, type PatchResult, PlanCatalogDoctorCheck, type PlannedFile, type ProjectKeyResult, type QuotaProviderFile, type QuotaSpec, type RenameResult, type RenameTable, type RewriteResult, type SchemaCheckReport, UI_VUE_SPECIFIER, USER_MANAGEMENT_PORT_TOKEN, USER_PORT_TOKEN, UserCommands, UserPortDoctorCheck, WhoAmIFlow, type WhoAmIResult, appKeyPattern, appendConstraints, applyFragmentBlocks, applyTokens, assertModelsExist, assertValidAppKey, assertValidQuotaKey, blankStringLiterals, blockBodyLines, breaksContract, buildImportMap, checkSchema, constraintsFor, enableFkPointers, extractBlockNames, extractBlocks, extractEnumBlocks, extractEnumNames, extractFragmentBlocks, extractModelBlocks, extractModelNames, findFkPointers, foreignKeyOf, hasBackRelation, hasConstraints, isNoLongerPublic, isOneToOne, judgeModuleResolution, kebabCase, migrationCreatedBy, minimumQuotasPerPlan, namedImports, parseBlockAttributes, parseEnumValues, parseFields, parseQuota, parseSchema, pascalCase, patchAppModule, patchOptionsFor, planInit, quotaKeyPattern, readEffectiveModuleResolution, relationNameOf, removeProjectKey, reportConstraints, rewriteImports, rewriteManifest, rewriteNames, rewriteSubpath, stripLineComment, structuralOnly, tablesAddressedBy };
+export { AUDIT_QUERY_PORT_TOKEN, AdminCommands, AdminManifestDoctorCheck, AdminMfaSetupCommand, AdminWhoamiCommand, type ApplyResult, AuditCommands, AuditTailCommand, AuditTailFlow, type AuditTailOptions, type BlockAttributeKind, type BlockAttributes, CLI_CONTEXT_CONFIG_TOKEN, CONSTRAINTS_MARKER, type CheckSeverity, type CliContextConfig, CliContextModule, type CliContextModuleOptions, CliContextService, CliError, type CliIdentity, type ConstraintsOutcome, type ConstraintsReport, DEFAULT_MANIFEST_CHECKS, DOCTOR_CHECKS_TOKEN, DiscoveryCommands, DiscoveryScanCommand, DiscoverySnapshotDoctorCheck, type DoctorCheck, type DoctorCheckResult, DoctorCommands, DoctorFlow, type DoctorReport, type EnableFkResult, type FieldMismatch, type FieldMismatchReason, type FieldSignature, type FkModelNames, type FkPointer, type FragmentBlocks, type InitOptions, type InitPlan, LIMIT_FILTER_IMPORTS, LIMIT_FILTER_PROVIDER, MANIFEST_ACCESS_PORT_TOKEN, MANIFEST_CHECKS_TOKEN, type ManifestCheck, ManifestCheckCommand, type ManifestCheckReport, type ManifestCheckResult, ManifestCliFlow, ManifestCommands, type ManifestDiff, ManifestDumpCommand, ManifestHashCommand, type ManifestRewriteOptions, ManifestValidateCommand, MfaSetupFlow, type MfaSetupOptions, type MfaSetupResult, type MissingBlockAttribute, type MissingEnumValue, type MissingField, type ModuleResolutionVerdict, type MoveTable, type MovedSetting, type MovedSettingOccurrence, type MovedSettingsResult, PLATFORM_DOCTOR_CHECK_PROVIDERS, type ParsedSchema, type PatchAppModuleOptions, type PatchOptionsFromPlan, type PatchResult, PlanCatalogDoctorCheck, type PlannedFile, type ProjectKeyResult, type QuotaProviderFile, type QuotaSpec, type RenameResult, type RenameTable, type RewriteResult, SCANNED_FOR_MOVED_SETTINGS, SETTINGS_THAT_MOVED, type SchemaCheckReport, UI_VUE_SPECIFIER, USER_MANAGEMENT_PORT_TOKEN, USER_PORT_TOKEN, UserCommands, UserPortDoctorCheck, WHERE_IT_GOES, WhoAmIFlow, type WhoAmIResult, type WrittenSetting, appKeyPattern, appendConstraints, applyFragmentBlocks, applyTokens, assertModelsExist, assertValidAppKey, assertValidQuotaKey, blankStringLiterals, blockBodyLines, breaksContract, buildImportMap, checkSchema, constraintsFor, enableFkPointers, extractBlockNames, extractBlocks, extractEnumBlocks, extractEnumNames, extractFragmentBlocks, extractModelBlocks, extractModelNames, findFkPointers, findMovedSettings, foreignKeyOf, hasBackRelation, hasConstraints, isNoLongerPublic, isOneToOne, judgeModuleResolution, kebabCase, migrationCreatedBy, minimumQuotasPerPlan, namedImports, parseBlockAttributes, parseEnumValues, parseFields, parseQuota, parseSchema, pascalCase, patchAppModule, patchOptionsFor, planInit, quotaKeyPattern, readEffectiveModuleResolution, relationNameOf, removeProjectKey, reportConstraints, rewriteImports, rewriteManifest, rewriteNames, rewriteSubpath, settingsWrittenTo, stripLineComment, structuralOnly, tablesAddressedBy };

package/dist/index.d.ts

@@ -869,6 +869,21 @@ declare function assertValidAppKey(appKey: string): void;
 /** The same, for a quota key. `additionalProperties: false` makes it a hard rule. */
 declare function assertValidQuotaKey(quotaKey: string): void;
 
+interface WrittenSetting {
+    /** Dotted path as it reads in the file, e.g. `tenantBilling.cancellationNoticeDays.monthly`. */
+    key: string;
+    /** The value as JSON — `0`, `[]`, `"EUR"` — so an empty list is visible as one. */
+    value: string;
+}
+/**
+ * The settings a generated `config/saas.yaml` carries.
+ *
+ * Loaded with the platform's own loader, not a YAML parse: a document `init`
+ * writes that the platform would refuse is a bug worth failing the generation
+ * for, rather than one the first boot reports after every file exists.
+ */
+declare function settingsWrittenTo(catalogYaml: string, source?: string): WrittenSetting[];
+
 /** One entry of the move table: where a file was, and where it went. */
 interface MoveTable {
     readonly moves: Readonly<Record<string, string>>;
@@ -1000,6 +1015,65 @@ interface ProjectKeyResult {
  */
 declare function removeProjectKey(text: string, kind?: 'source' | 'yaml'): ProjectKeyResult;
 
+/**
+ * The settings that belong in `config/saas.yaml#tenantBilling`, read off the
+ * schema that defines them.
+ *
+ * Not a list here, and not a copy of the one in `@saasicat/nest`: both derive
+ * from the same schema, so the day a third setting moves into that block, this
+ * codemod names it and the module refuses it without either being edited.
+ */
+declare const SETTINGS_THAT_MOVED: readonly string[];
+type MovedSetting = string;
+interface MovedSettingOccurrence {
+    /** Which setting it is, so the report can say where it goes. */
+    readonly setting: MovedSetting;
+    /** 1-based line number. */
+    readonly line: number;
+}
+interface MovedSettingsResult {
+    readonly occurrences: readonly MovedSettingOccurrence[];
+}
+/**
+ * Files a moved setting can actually be passed in.
+ *
+ * The codemod walk includes Markdown, and both consumers keep large
+ * documentation folders — an upgrade note that mentions `cancellationNoticeDays`
+ * would land in the report beside the line somebody has to change, and a report
+ * that mixes the two is one nobody reads twice. Prose cannot pass a module
+ * option, so prose is not scanned.
+ */
+declare const SCANNED_FOR_MOVED_SETTINGS: RegExp;
+/**
+ * Every occurrence of a moved setting in one source file.
+ *
+ * Matched on word boundaries alone: a longer name that contains it
+ * (`cancellationNoticeDaysV2`) is not reported, and everything else is —
+ * including a mention in a comment or a string.
+ *
+ * That last part is deliberate, and it is the opposite trade from the one this
+ * comment used to claim. Requiring a colon would read as "only a property",
+ * and it would then miss `{ cancellationNoticeDays }` and
+ * `const { cancellationNoticeDays } = options` — two ordinary ways to pass the
+ * same option. Telling a comment from code needs the grammar, which this does
+ * not have. So it over-reports inside code, where the cost is a glance, rather
+ * than under-reporting, where the cost is somebody not learning that their
+ * value is about to stop being read.
+ *
+ * A property access (`config.cancellationNoticeDays`) is reported too: reading
+ * the value back from module options is the same migration, one step further
+ * along.
+ */
+declare function findMovedSettings(text: string): MovedSettingsResult;
+/**
+ * Where a setting goes, for the report.
+ *
+ * One sentence per setting rather than one for both: they end up in the same
+ * block and mean different things, and "move these two to the file" is the
+ * instruction people follow halfway.
+ */
+declare const WHERE_IT_GOES: Record<string, string>;
+
 interface PatchAppModuleOptions {
     /** Import specifier for the persistence bundle, or null when not generated. */
     persistenceImport: string | null;
@@ -1243,4 +1317,4 @@ declare class UserCommands extends CommandRunner {
     parsePassword(val: string): string;
 }
 
-export { AUDIT_QUERY_PORT_TOKEN, AdminCommands, AdminManifestDoctorCheck, AdminMfaSetupCommand, AdminWhoamiCommand, type ApplyResult, AuditCommands, AuditTailCommand, AuditTailFlow, type AuditTailOptions, type BlockAttributeKind, type BlockAttributes, CLI_CONTEXT_CONFIG_TOKEN, CONSTRAINTS_MARKER, type CheckSeverity, type CliContextConfig, CliContextModule, type CliContextModuleOptions, CliContextService, CliError, type CliIdentity, type ConstraintsOutcome, type ConstraintsReport, DEFAULT_MANIFEST_CHECKS, DOCTOR_CHECKS_TOKEN, DiscoveryCommands, DiscoveryScanCommand, DiscoverySnapshotDoctorCheck, type DoctorCheck, type DoctorCheckResult, DoctorCommands, DoctorFlow, type DoctorReport, type EnableFkResult, type FieldMismatch, type FieldMismatchReason, type FieldSignature, type FkModelNames, type FkPointer, type FragmentBlocks, type InitOptions, type InitPlan, LIMIT_FILTER_IMPORTS, LIMIT_FILTER_PROVIDER, MANIFEST_ACCESS_PORT_TOKEN, MANIFEST_CHECKS_TOKEN, type ManifestCheck, ManifestCheckCommand, type ManifestCheckReport, type ManifestCheckResult, ManifestCliFlow, ManifestCommands, type ManifestDiff, ManifestDumpCommand, ManifestHashCommand, type ManifestRewriteOptions, ManifestValidateCommand, MfaSetupFlow, type MfaSetupOptions, type MfaSetupResult, type MissingBlockAttribute, type MissingEnumValue, type MissingField, type ModuleResolutionVerdict, type MoveTable, PLATFORM_DOCTOR_CHECK_PROVIDERS, type ParsedSchema, type PatchAppModuleOptions, type PatchOptionsFromPlan, type PatchResult, PlanCatalogDoctorCheck, type PlannedFile, type ProjectKeyResult, type QuotaProviderFile, type QuotaSpec, type RenameResult, type RenameTable, type RewriteResult, type SchemaCheckReport, UI_VUE_SPECIFIER, USER_MANAGEMENT_PORT_TOKEN, USER_PORT_TOKEN, UserCommands, UserPortDoctorCheck, WhoAmIFlow, type WhoAmIResult, appKeyPattern, appendConstraints, applyFragmentBlocks, applyTokens, assertModelsExist, assertValidAppKey, assertValidQuotaKey, blankStringLiterals, blockBodyLines, breaksContract, buildImportMap, checkSchema, constraintsFor, enableFkPointers, extractBlockNames, extractBlocks, extractEnumBlocks, extractEnumNames, extractFragmentBlocks, extractModelBlocks, extractModelNames, findFkPointers, foreignKeyOf, hasBackRelation, hasConstraints, isNoLongerPublic, isOneToOne, judgeModuleResolution, kebabCase, migrationCreatedBy, minimumQuotasPerPlan, namedImports, parseBlockAttributes, parseEnumValues, parseFields, parseQuota, parseSchema, pascalCase, patchAppModule, patchOptionsFor, planInit, quotaKeyPattern, readEffectiveModuleResolution, relationNameOf, removeProjectKey, reportConstraints, rewriteImports, rewriteManifest, rewriteNames, rewriteSubpath, stripLineComment, structuralOnly, tablesAddressedBy };
+export { AUDIT_QUERY_PORT_TOKEN, AdminCommands, AdminManifestDoctorCheck, AdminMfaSetupCommand, AdminWhoamiCommand, type ApplyResult, AuditCommands, AuditTailCommand, AuditTailFlow, type AuditTailOptions, type BlockAttributeKind, type BlockAttributes, CLI_CONTEXT_CONFIG_TOKEN, CONSTRAINTS_MARKER, type CheckSeverity, type CliContextConfig, CliContextModule, type CliContextModuleOptions, CliContextService, CliError, type CliIdentity, type ConstraintsOutcome, type ConstraintsReport, DEFAULT_MANIFEST_CHECKS, DOCTOR_CHECKS_TOKEN, DiscoveryCommands, DiscoveryScanCommand, DiscoverySnapshotDoctorCheck, type DoctorCheck, type DoctorCheckResult, DoctorCommands, DoctorFlow, type DoctorReport, type EnableFkResult, type FieldMismatch, type FieldMismatchReason, type FieldSignature, type FkModelNames, type FkPointer, type FragmentBlocks, type InitOptions, type InitPlan, LIMIT_FILTER_IMPORTS, LIMIT_FILTER_PROVIDER, MANIFEST_ACCESS_PORT_TOKEN, MANIFEST_CHECKS_TOKEN, type ManifestCheck, ManifestCheckCommand, type ManifestCheckReport, type ManifestCheckResult, ManifestCliFlow, ManifestCommands, type ManifestDiff, ManifestDumpCommand, ManifestHashCommand, type ManifestRewriteOptions, ManifestValidateCommand, MfaSetupFlow, type MfaSetupOptions, type MfaSetupResult, type MissingBlockAttribute, type MissingEnumValue, type MissingField, type ModuleResolutionVerdict, type MoveTable, type MovedSetting, type MovedSettingOccurrence, type MovedSettingsResult, PLATFORM_DOCTOR_CHECK_PROVIDERS, type ParsedSchema, type PatchAppModuleOptions, type PatchOptionsFromPlan, type PatchResult, PlanCatalogDoctorCheck, type PlannedFile, type ProjectKeyResult, type QuotaProviderFile, type QuotaSpec, type RenameResult, type RenameTable, type RewriteResult, SCANNED_FOR_MOVED_SETTINGS, SETTINGS_THAT_MOVED, type SchemaCheckReport, UI_VUE_SPECIFIER, USER_MANAGEMENT_PORT_TOKEN, USER_PORT_TOKEN, UserCommands, UserPortDoctorCheck, WHERE_IT_GOES, WhoAmIFlow, type WhoAmIResult, type WrittenSetting, appKeyPattern, appendConstraints, applyFragmentBlocks, applyTokens, assertModelsExist, assertValidAppKey, assertValidQuotaKey, blankStringLiterals, blockBodyLines, breaksContract, buildImportMap, checkSchema, constraintsFor, enableFkPointers, extractBlockNames, extractBlocks, extractEnumBlocks, extractEnumNames, extractFragmentBlocks, extractModelBlocks, extractModelNames, findFkPointers, findMovedSettings, foreignKeyOf, hasBackRelation, hasConstraints, isNoLongerPublic, isOneToOne, judgeModuleResolution, kebabCase, migrationCreatedBy, minimumQuotasPerPlan, namedImports, parseBlockAttributes, parseEnumValues, parseFields, parseQuota, parseSchema, pascalCase, patchAppModule, patchOptionsFor, planInit, quotaKeyPattern, readEffectiveModuleResolution, relationNameOf, removeProjectKey, reportConstraints, rewriteImports, rewriteManifest, rewriteNames, rewriteSubpath, settingsWrittenTo, stripLineComment, structuralOnly, tablesAddressedBy };

package/dist/index.js

@@ -1783,6 +1783,31 @@ function readEffectiveModuleResolution(root, ts) {
 }
 __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/",
@@ -2158,6 +2183,43 @@ function removeFromYaml(text) {
 }
 __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/init/patch-app-module.ts
 var MARKER = "SaaSiCatModule.forRoot";
 function patchAppModule(source, options) {
@@ -3374,11 +3436,14 @@ export {
   MfaSetupFlow,
   PLATFORM_DOCTOR_CHECK_PROVIDERS,
   PlanCatalogDoctorCheck,
+  SCANNED_FOR_MOVED_SETTINGS,
+  SETTINGS_THAT_MOVED,
   UI_VUE_SPECIFIER,
   USER_MANAGEMENT_PORT_TOKEN,
   USER_PORT_TOKEN,
   UserCommands,
   UserPortDoctorCheck,
+  WHERE_IT_GOES,
   WhoAmIFlow,
   appKeyPattern,
   appendConstraints,
@@ -3402,6 +3467,7 @@ export {
   extractModelBlocks,
   extractModelNames,
   findFkPointers,
+  findMovedSettings,
   foreignKeyOf,
   hasBackRelation,
   hasConstraints,
@@ -3430,6 +3496,7 @@ export {
   rewriteManifest,
   rewriteNames,
   rewriteSubpath,
+  settingsWrittenTo,
   stripLineComment,
   structuralOnly,
   tablesAddressedBy

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@saasicat/cli",
-  "version": "1.0.0-rc.7",
+  "version": "1.0.0-rc.9",
   "description": "CLI helpers for SaaS platform consumers. Provides CliContextService (identity, MFA, production confirm, audit tag).",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -30,9 +30,9 @@
   },
   "dependencies": {
     "qrcode-terminal": "^0.12.0",
-    "@saasicat/nest": "^1.0.0-rc.7",
-    "@saasicat/spec": "^1.0.0-rc.7",
-    "@saasicat/core": "^1.0.0-rc.7"
+    "@saasicat/nest": "^1.0.0-rc.9",
+    "@saasicat/spec": "^1.0.0-rc.9",
+    "@saasicat/core": "^1.0.0-rc.9"
   },
   "peerDependencies": {
     "@nestjs/common": "^11.0.0",

package/templates/init/config/saas.yaml.tpl

@@ -7,6 +7,30 @@ app:
 currency: EUR
 vatRate: 19.0
 
+# What the tenant self-service routes may do, and on what terms. These live
+# here and nowhere else — an operator reading this file has to be reading the
+# values that are running, with no "unless somebody passed it in code"
+# attached. The file is read at boot, so an edit lands on the next restart.
+tenantBilling:
+    # How many days before the term ends a cancellation is still in time.
+    # Zero means there is no door to be shut out of: a cancellation on the last
+    # day still lands at the term end. Raise it and the cut is hard — a
+    # declaration made after the window lands one full period later, which on a
+    # yearly cycle is a year.
+    #
+    # Two rhythms, two numbers, and both are required. A month and a year
+    # cannot share a notice period, and a rhythm left out would read as zero:
+    # a commercial decision nobody made.
+    cancellationNoticeDays:
+        monthly: 0
+        yearly: 0
+    # Plans a tenant may not reach or leave on its own — typically a plan that
+    # only a special contract activates. Empty is a statement, not an omission:
+    # it says self-service reaches every plan.
+    selfServiceBlockedPlans:
+        asTarget: []
+        asSource: []
+
 marketing:
     availableLocales: [en]