@saasicat/cli 1.0.0-rc.2 → 1.0.0-rc.20

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { MfaService, AdminAuditService, AdminManifestService, DiscoverySnapshot, ProviderSpec, DiscoveryScanner } from '@saasicat/nest';
+import { MfaService, AdminAuditService, AdminManifestService, DiscoverySnapshot, IssuerIdentityInspector, ProviderSpec, DiscoveryScanner } from '@saasicat/nest';
 import { UserPort, PlatformUserDto, AuditQueryPort, AuditEntry, AdminManifest, ManifestAccessPort, PlanCatalog, UserManagementPort } from '@saasicat/core';
 import { Type, DynamicModule } from '@nestjs/common';
 import * as TypeScript from 'typescript';
@@ -311,6 +311,28 @@ declare class AdminManifestDoctorCheck implements DoctorCheck {
     constructor(manifest: AdminManifestService);
     run(): Promise<DoctorCheckResult>;
 }
+/**
+ * The issuer identity, and what changing it would cost.
+ *
+ * A start compares the issuer in `config/saas.yaml` with the identity the
+ * installation recorded and refuses an undeclared difference, because moving a
+ * contract to another legal entity is a transfer and not an edit of a setting.
+ * This asks the same question without acting on it and says, while nothing has
+ * moved, what a change would cost.
+ *
+ * It does NOT turn a refusal into a report where the same application also
+ * mounts the platform's boot check: that check runs at `init()`, so the CLI
+ * process carrying it is refused before any command runs — with the same
+ * message, which is the point. The `refused` branch below is for a diagnostic
+ * that runs without the hook.
+ */
+declare class IssuerIdentityDoctorCheck implements DoctorCheck {
+    private readonly issuer;
+    readonly id = "platform.issuer-identity";
+    readonly label = "Issuer identity against the recorded one";
+    constructor(issuer: IssuerIdentityInspector);
+    run(): Promise<DoctorCheckResult>;
+}
 /**
  * Default list that consumers can spread in `CliContextModule.forRoot({ doctorChecks })`:
  *
@@ -467,6 +489,15 @@ interface MissingBlockAttribute {
     /** For `map`: what the consumer maps to instead. */
     actual?: string;
 }
+/**
+ * A relation that deletes a record the platform keeps past its tenant, together
+ * with the tenant.
+ */
+interface TenantCascade {
+    model: string;
+    /** The relation field that cascades, e.g. `tenant`. */
+    field: string;
+}
 interface SchemaCheckReport {
     /** Platform models the consumer does not carry — informational. */
     absentModels: string[];
@@ -480,6 +511,11 @@ interface SchemaCheckReport {
      * `@@index`, `@@unique`, and a diverging `@@map`.
      */
     missingBlockAttributes: MissingBlockAttribute[];
+    /**
+     * Relations that cascade from the tenant onto a model the platform keeps
+     * after the tenant is gone, such as a contract.
+     */
+    tenantCascades: TenantCascade[];
     /** Models present in both schemas, i.e. actually compared. */
     checkedModelCount: number;
     /** Enums present in both schemas, i.e. actually compared. */
@@ -514,11 +550,24 @@ declare function parseSchema(schema: string): ParsedSchema;
  * the check.
  */
 declare function breaksContract(attribute: MissingBlockAttribute): boolean;
+/**
+ * The platform models that outlive their tenant: the ones whose fragment
+ * declares `tenantId` and deliberately comments no relation to `Tenant`.
+ *
+ * Read off the fragments rather than listed, so the next model kept past its
+ * tenant is covered by being written that way. Every other model with a
+ * `tenantId` ships the pointer a consumer enables, cascade and all.
+ */
+declare function modelsKeptPastTheTenant(specSchema: string): string[];
 /**
  * Compares a consumer schema against the canonical fragments. `specSchema` is
  * the concatenation of the fragments the check should cover.
+ *
+ * @param knownModels Every model the shipped fragments declare, where the spec
+ * passed in is a narrowed selection of them (`schema check --fragments=…`).
+ * Omitted, the spec is taken to be the whole of it.
  */
-declare function checkSchema(specSchema: string, appSchema: string): SchemaCheckReport;
+declare function checkSchema(specSchema: string, appSchema: string, knownModels?: ReadonlySet<string>): SchemaCheckReport;
 
 /** Marks the block this tool appends, and lets it recognise its own work. */
 declare const CONSTRAINTS_MARKER = "-- saasicat:constraints";
@@ -719,9 +768,9 @@ declare function assertModelsExist(declaredModels: readonly string[], models: Fk
 
 /** What the caller asked for. */
 interface InitOptions {
-    /** The catalogue this app administers. Also the storage-key prefix. */
-    projectKey: string;
-    /** Human name in the manifest and the YAML. Defaults to `projectKey`. */
+    /** Slug of the application: npm package name, storage-key prefix, id prefix. */
+    appKey: string;
+    /** Human name in the manifest and the YAML. Defaults to `appKey`. */
     appName?: string;
     /** Admin API prefix, e.g. `/api/v1/admin`. */
     apiBase?: string;
@@ -854,8 +903,7 @@ declare function judgeModuleResolution(value: string | null): ModuleResolutionVe
  */
 declare function readEffectiveModuleResolution(root: string, ts: typeof TypeScript): string | null;
 
-/** The pattern `plan-catalog.schema.json` puts on `projectKey`. */
-declare function projectKeyPattern(): RegExp;
+declare function appKeyPattern(): RegExp;
 /** The pattern it puts on the keys inside a plan's `quotas` object. */
 declare function quotaKeyPattern(): RegExp;
 /** How many quotas a plan must declare — 1 today, and read rather than assumed. */
@@ -866,10 +914,25 @@ declare function minimumQuotasPerPlan(): number;
  * The message carries the pattern rather than a prose paraphrase, because the
  * paraphrase is what goes stale.
  */
-declare function assertValidProjectKey(projectKey: string): void;
+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>>;
@@ -981,6 +1044,147 @@ interface ManifestRewriteOptions {
 }
 declare function rewriteManifest(text: string, table: RenameTable, options: ManifestRewriteOptions): RenameResult;
 
+interface ProjectKeyResult {
+    readonly text: string;
+    /** How many occurrences were taken out. */
+    readonly rewritten: number;
+    /**
+     * 1-based line numbers of the occurrences left in place.
+     *
+     * Reported rather than removed: the codemod could not tell them from a
+     * consumer's own field, and a wrong deletion is worse than a named one.
+     */
+    readonly undecided: readonly number[];
+}
+/**
+ * Rewrites one source file.
+ *
+ * `yaml` switches to the config form: there the field is a top-level key in a
+ * file the platform owns the schema of, so it is decidable without an anchor.
+ */
+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>;
+
+/** Which files a `dbCatalog` can be passed in: code, not prose. */
+declare const SCANNED_FOR_DB_CATALOG: RegExp;
+type DbCatalogShape = 'values' | 'mixed' | 'reference';
+interface DbCatalogOccurrence {
+    /** 1-based line of the `dbCatalog:` property. */
+    readonly line: number;
+    /**
+     * `values` — an object literal with no `path`: the old shape whole.
+     * `mixed` — a `path` with something beside it that the option does not
+     * take: an upgrade that stopped halfway, and the platform refuses it too.
+     * `reference` — anything else on the right of the colon: a variable, a
+     * call, a spread. This cannot see what it carries, so it is named for a
+     * person to look at rather than passed over.
+     */
+    readonly shape: DbCatalogShape;
+    /**
+     * The members that are not what the option takes — every one of a
+     * `values` block, the ones left beside the path of a `mixed` one, and
+     * nothing for a `reference`. A spread is listed as `...name`, because
+     * what it carries is decided elsewhere.
+     */
+    readonly leftovers: readonly string[];
+}
+interface DbCatalogResult {
+    readonly occurrences: readonly DbCatalogOccurrence[];
+}
+/**
+ * Every `dbCatalog:` property in one source file, with what stands to its right.
+ *
+ * A property in code, which means the name followed by a colon, outside any
+ * comment or string. The other codemod in this family reports every
+ * word-boundary mention of a setting, including one in a comment, on the
+ * reasoning that over-reporting inside code costs a glance. That reasoning
+ * does not carry here: `saasicat init` writes the sentence "pass `dbCatalog`
+ * instead" into every generated `app.module.ts`, so a mention is the normal
+ * case and a report of it would be noise on every upgrade — and a block
+ * commented out, or quoted as a sample, is migration work that does not
+ * exist. An OPTIONAL type member (`dbCatalog?:`) is not a property either: the
+ * `?` stands where the colon would. A required one (`dbCatalog: DbCatalogOptions`)
+ * is the same tokens as a value passed in from elsewhere, and is reported as a
+ * `reference` for that reason — a glance, which is what `reference` is for. A
+ * shorthand `{ dbCatalog }` is not seen — the value it carries is elsewhere,
+ * and the module's refusal names it at boot.
+ *
+ * What counts as migrated is read off `DB_CATALOG_MEMBERS`, the list the
+ * platform's own refusal reads, so the two cannot disagree about a block.
+ */
+declare function findDbCatalogBlocks(text: string): DbCatalogResult;
+/**
+ * What is wrong with one occurrence, in the words the report uses.
+ *
+ * Beside the shapes rather than in the printer, because one of them has no
+ * leftovers to name: a `values` block whose only member is one the option
+ * takes — `dbCatalog: { env: process.env }` — or one emptied mid-edit is
+ * genuinely broken and genuinely refused at boot, but "carries the values:"
+ * with nothing after it names a file to go and look at without saying what to
+ * look for.
+ */
+declare function describeDbCatalogOccurrence(occurrence: Pick<DbCatalogOccurrence, 'shape' | 'leftovers'>): string;
+/** What to write instead, for the report. */
+declare const WHERE_DB_CATALOG_GOES: string;
+
 interface PatchAppModuleOptions {
     /** Import specifier for the persistence bundle, or null when not generated. */
     persistenceImport: string | null;
@@ -1048,15 +1252,18 @@ interface CliContextModuleOptions {
      * — `<app> doctor` runs but returns no content. Consumers register
      * project-specific checks.
      *
-     * Note: if `defaultDoctorChecks: true`, the 4 platform standard checks
-     * (PlanCatalog/Discovery/UserPort/AdminManifest) are registered **in
-     * addition** to this list.
+     * Note: if `defaultDoctorChecks: true`, the platform's own checks —
+     * `PLATFORM_DOCTOR_CHECK_PROVIDERS` — are registered **in addition** to
+     * this list. They are named there rather than here: a second list of them
+     * in prose is the copy that goes stale.
      */
     doctorChecks?: ProviderSpec<DoctorCheck[]>;
     /**
-     * Default `false`. If `true`, the platform registers the four standard
-     * checks from `PLATFORM_DOCTOR_CHECK_PROVIDERS` in addition to
-     * `doctorChecks`. Recommended for all apps that take `<app> doctor` seriously.
+     * Default `false`. If `true`, the platform registers the checks from
+     * `PLATFORM_DOCTOR_CHECK_PROVIDERS` in addition to `doctorChecks`. They
+     * resolve what `SaaSiCatModule` provides, so an application that wires the
+     * platform's modules by hand registers the ones it can serve instead.
+     * Recommended for all apps that take `<app> doctor` seriously.
      */
     defaultDoctorChecks?: boolean;
     /**
@@ -1224,4 +1431,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 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, appendConstraints, applyFragmentBlocks, applyTokens, assertModelsExist, assertValidProjectKey, 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, projectKeyPattern, quotaKeyPattern, readEffectiveModuleResolution, relationNameOf, 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, type DbCatalogOccurrence, type DbCatalogResult, type DbCatalogShape, 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, IssuerIdentityDoctorCheck, 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_DB_CATALOG, SCANNED_FOR_MOVED_SETTINGS, SETTINGS_THAT_MOVED, type SchemaCheckReport, type TenantCascade, UI_VUE_SPECIFIER, USER_MANAGEMENT_PORT_TOKEN, USER_PORT_TOKEN, UserCommands, UserPortDoctorCheck, WHERE_DB_CATALOG_GOES, WHERE_IT_GOES, WhoAmIFlow, type WhoAmIResult, type WrittenSetting, appKeyPattern, appendConstraints, applyFragmentBlocks, applyTokens, assertModelsExist, assertValidAppKey, assertValidQuotaKey, blankStringLiterals, blockBodyLines, breaksContract, buildImportMap, checkSchema, constraintsFor, describeDbCatalogOccurrence, enableFkPointers, extractBlockNames, extractBlocks, extractEnumBlocks, extractEnumNames, extractFragmentBlocks, extractModelBlocks, extractModelNames, findDbCatalogBlocks, findFkPointers, findMovedSettings, foreignKeyOf, hasBackRelation, hasConstraints, isNoLongerPublic, isOneToOne, judgeModuleResolution, kebabCase, migrationCreatedBy, minimumQuotasPerPlan, modelsKeptPastTheTenant, 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

@@ -1,4 +1,4 @@
-import { MfaService, AdminAuditService, AdminManifestService, DiscoverySnapshot, ProviderSpec, DiscoveryScanner } from '@saasicat/nest';
+import { MfaService, AdminAuditService, AdminManifestService, DiscoverySnapshot, IssuerIdentityInspector, ProviderSpec, DiscoveryScanner } from '@saasicat/nest';
 import { UserPort, PlatformUserDto, AuditQueryPort, AuditEntry, AdminManifest, ManifestAccessPort, PlanCatalog, UserManagementPort } from '@saasicat/core';
 import { Type, DynamicModule } from '@nestjs/common';
 import * as TypeScript from 'typescript';
@@ -311,6 +311,28 @@ declare class AdminManifestDoctorCheck implements DoctorCheck {
     constructor(manifest: AdminManifestService);
     run(): Promise<DoctorCheckResult>;
 }
+/**
+ * The issuer identity, and what changing it would cost.
+ *
+ * A start compares the issuer in `config/saas.yaml` with the identity the
+ * installation recorded and refuses an undeclared difference, because moving a
+ * contract to another legal entity is a transfer and not an edit of a setting.
+ * This asks the same question without acting on it and says, while nothing has
+ * moved, what a change would cost.
+ *
+ * It does NOT turn a refusal into a report where the same application also
+ * mounts the platform's boot check: that check runs at `init()`, so the CLI
+ * process carrying it is refused before any command runs — with the same
+ * message, which is the point. The `refused` branch below is for a diagnostic
+ * that runs without the hook.
+ */
+declare class IssuerIdentityDoctorCheck implements DoctorCheck {
+    private readonly issuer;
+    readonly id = "platform.issuer-identity";
+    readonly label = "Issuer identity against the recorded one";
+    constructor(issuer: IssuerIdentityInspector);
+    run(): Promise<DoctorCheckResult>;
+}
 /**
  * Default list that consumers can spread in `CliContextModule.forRoot({ doctorChecks })`:
  *
@@ -467,6 +489,15 @@ interface MissingBlockAttribute {
     /** For `map`: what the consumer maps to instead. */
     actual?: string;
 }
+/**
+ * A relation that deletes a record the platform keeps past its tenant, together
+ * with the tenant.
+ */
+interface TenantCascade {
+    model: string;
+    /** The relation field that cascades, e.g. `tenant`. */
+    field: string;
+}
 interface SchemaCheckReport {
     /** Platform models the consumer does not carry — informational. */
     absentModels: string[];
@@ -480,6 +511,11 @@ interface SchemaCheckReport {
      * `@@index`, `@@unique`, and a diverging `@@map`.
      */
     missingBlockAttributes: MissingBlockAttribute[];
+    /**
+     * Relations that cascade from the tenant onto a model the platform keeps
+     * after the tenant is gone, such as a contract.
+     */
+    tenantCascades: TenantCascade[];
     /** Models present in both schemas, i.e. actually compared. */
     checkedModelCount: number;
     /** Enums present in both schemas, i.e. actually compared. */
@@ -514,11 +550,24 @@ declare function parseSchema(schema: string): ParsedSchema;
  * the check.
  */
 declare function breaksContract(attribute: MissingBlockAttribute): boolean;
+/**
+ * The platform models that outlive their tenant: the ones whose fragment
+ * declares `tenantId` and deliberately comments no relation to `Tenant`.
+ *
+ * Read off the fragments rather than listed, so the next model kept past its
+ * tenant is covered by being written that way. Every other model with a
+ * `tenantId` ships the pointer a consumer enables, cascade and all.
+ */
+declare function modelsKeptPastTheTenant(specSchema: string): string[];
 /**
  * Compares a consumer schema against the canonical fragments. `specSchema` is
  * the concatenation of the fragments the check should cover.
+ *
+ * @param knownModels Every model the shipped fragments declare, where the spec
+ * passed in is a narrowed selection of them (`schema check --fragments=…`).
+ * Omitted, the spec is taken to be the whole of it.
  */
-declare function checkSchema(specSchema: string, appSchema: string): SchemaCheckReport;
+declare function checkSchema(specSchema: string, appSchema: string, knownModels?: ReadonlySet<string>): SchemaCheckReport;
 
 /** Marks the block this tool appends, and lets it recognise its own work. */
 declare const CONSTRAINTS_MARKER = "-- saasicat:constraints";
@@ -719,9 +768,9 @@ declare function assertModelsExist(declaredModels: readonly string[], models: Fk
 
 /** What the caller asked for. */
 interface InitOptions {
-    /** The catalogue this app administers. Also the storage-key prefix. */
-    projectKey: string;
-    /** Human name in the manifest and the YAML. Defaults to `projectKey`. */
+    /** Slug of the application: npm package name, storage-key prefix, id prefix. */
+    appKey: string;
+    /** Human name in the manifest and the YAML. Defaults to `appKey`. */
     appName?: string;
     /** Admin API prefix, e.g. `/api/v1/admin`. */
     apiBase?: string;
@@ -854,8 +903,7 @@ declare function judgeModuleResolution(value: string | null): ModuleResolutionVe
  */
 declare function readEffectiveModuleResolution(root: string, ts: typeof TypeScript): string | null;
 
-/** The pattern `plan-catalog.schema.json` puts on `projectKey`. */
-declare function projectKeyPattern(): RegExp;
+declare function appKeyPattern(): RegExp;
 /** The pattern it puts on the keys inside a plan's `quotas` object. */
 declare function quotaKeyPattern(): RegExp;
 /** How many quotas a plan must declare — 1 today, and read rather than assumed. */
@@ -866,10 +914,25 @@ declare function minimumQuotasPerPlan(): number;
  * The message carries the pattern rather than a prose paraphrase, because the
  * paraphrase is what goes stale.
  */
-declare function assertValidProjectKey(projectKey: string): void;
+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>>;
@@ -981,6 +1044,147 @@ interface ManifestRewriteOptions {
 }
 declare function rewriteManifest(text: string, table: RenameTable, options: ManifestRewriteOptions): RenameResult;
 
+interface ProjectKeyResult {
+    readonly text: string;
+    /** How many occurrences were taken out. */
+    readonly rewritten: number;
+    /**
+     * 1-based line numbers of the occurrences left in place.
+     *
+     * Reported rather than removed: the codemod could not tell them from a
+     * consumer's own field, and a wrong deletion is worse than a named one.
+     */
+    readonly undecided: readonly number[];
+}
+/**
+ * Rewrites one source file.
+ *
+ * `yaml` switches to the config form: there the field is a top-level key in a
+ * file the platform owns the schema of, so it is decidable without an anchor.
+ */
+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>;
+
+/** Which files a `dbCatalog` can be passed in: code, not prose. */
+declare const SCANNED_FOR_DB_CATALOG: RegExp;
+type DbCatalogShape = 'values' | 'mixed' | 'reference';
+interface DbCatalogOccurrence {
+    /** 1-based line of the `dbCatalog:` property. */
+    readonly line: number;
+    /**
+     * `values` — an object literal with no `path`: the old shape whole.
+     * `mixed` — a `path` with something beside it that the option does not
+     * take: an upgrade that stopped halfway, and the platform refuses it too.
+     * `reference` — anything else on the right of the colon: a variable, a
+     * call, a spread. This cannot see what it carries, so it is named for a
+     * person to look at rather than passed over.
+     */
+    readonly shape: DbCatalogShape;
+    /**
+     * The members that are not what the option takes — every one of a
+     * `values` block, the ones left beside the path of a `mixed` one, and
+     * nothing for a `reference`. A spread is listed as `...name`, because
+     * what it carries is decided elsewhere.
+     */
+    readonly leftovers: readonly string[];
+}
+interface DbCatalogResult {
+    readonly occurrences: readonly DbCatalogOccurrence[];
+}
+/**
+ * Every `dbCatalog:` property in one source file, with what stands to its right.
+ *
+ * A property in code, which means the name followed by a colon, outside any
+ * comment or string. The other codemod in this family reports every
+ * word-boundary mention of a setting, including one in a comment, on the
+ * reasoning that over-reporting inside code costs a glance. That reasoning
+ * does not carry here: `saasicat init` writes the sentence "pass `dbCatalog`
+ * instead" into every generated `app.module.ts`, so a mention is the normal
+ * case and a report of it would be noise on every upgrade — and a block
+ * commented out, or quoted as a sample, is migration work that does not
+ * exist. An OPTIONAL type member (`dbCatalog?:`) is not a property either: the
+ * `?` stands where the colon would. A required one (`dbCatalog: DbCatalogOptions`)
+ * is the same tokens as a value passed in from elsewhere, and is reported as a
+ * `reference` for that reason — a glance, which is what `reference` is for. A
+ * shorthand `{ dbCatalog }` is not seen — the value it carries is elsewhere,
+ * and the module's refusal names it at boot.
+ *
+ * What counts as migrated is read off `DB_CATALOG_MEMBERS`, the list the
+ * platform's own refusal reads, so the two cannot disagree about a block.
+ */
+declare function findDbCatalogBlocks(text: string): DbCatalogResult;
+/**
+ * What is wrong with one occurrence, in the words the report uses.
+ *
+ * Beside the shapes rather than in the printer, because one of them has no
+ * leftovers to name: a `values` block whose only member is one the option
+ * takes — `dbCatalog: { env: process.env }` — or one emptied mid-edit is
+ * genuinely broken and genuinely refused at boot, but "carries the values:"
+ * with nothing after it names a file to go and look at without saying what to
+ * look for.
+ */
+declare function describeDbCatalogOccurrence(occurrence: Pick<DbCatalogOccurrence, 'shape' | 'leftovers'>): string;
+/** What to write instead, for the report. */
+declare const WHERE_DB_CATALOG_GOES: string;
+
 interface PatchAppModuleOptions {
     /** Import specifier for the persistence bundle, or null when not generated. */
     persistenceImport: string | null;
@@ -1048,15 +1252,18 @@ interface CliContextModuleOptions {
      * — `<app> doctor` runs but returns no content. Consumers register
      * project-specific checks.
      *
-     * Note: if `defaultDoctorChecks: true`, the 4 platform standard checks
-     * (PlanCatalog/Discovery/UserPort/AdminManifest) are registered **in
-     * addition** to this list.
+     * Note: if `defaultDoctorChecks: true`, the platform's own checks —
+     * `PLATFORM_DOCTOR_CHECK_PROVIDERS` — are registered **in addition** to
+     * this list. They are named there rather than here: a second list of them
+     * in prose is the copy that goes stale.
      */
     doctorChecks?: ProviderSpec<DoctorCheck[]>;
     /**
-     * Default `false`. If `true`, the platform registers the four standard
-     * checks from `PLATFORM_DOCTOR_CHECK_PROVIDERS` in addition to
-     * `doctorChecks`. Recommended for all apps that take `<app> doctor` seriously.
+     * Default `false`. If `true`, the platform registers the checks from
+     * `PLATFORM_DOCTOR_CHECK_PROVIDERS` in addition to `doctorChecks`. They
+     * resolve what `SaaSiCatModule` provides, so an application that wires the
+     * platform's modules by hand registers the ones it can serve instead.
+     * Recommended for all apps that take `<app> doctor` seriously.
      */
     defaultDoctorChecks?: boolean;
     /**
@@ -1224,4 +1431,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 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, appendConstraints, applyFragmentBlocks, applyTokens, assertModelsExist, assertValidProjectKey, 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, projectKeyPattern, quotaKeyPattern, readEffectiveModuleResolution, relationNameOf, 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, type DbCatalogOccurrence, type DbCatalogResult, type DbCatalogShape, 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, IssuerIdentityDoctorCheck, 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_DB_CATALOG, SCANNED_FOR_MOVED_SETTINGS, SETTINGS_THAT_MOVED, type SchemaCheckReport, type TenantCascade, UI_VUE_SPECIFIER, USER_MANAGEMENT_PORT_TOKEN, USER_PORT_TOKEN, UserCommands, UserPortDoctorCheck, WHERE_DB_CATALOG_GOES, WHERE_IT_GOES, WhoAmIFlow, type WhoAmIResult, type WrittenSetting, appKeyPattern, appendConstraints, applyFragmentBlocks, applyTokens, assertModelsExist, assertValidAppKey, assertValidQuotaKey, blankStringLiterals, blockBodyLines, breaksContract, buildImportMap, checkSchema, constraintsFor, describeDbCatalogOccurrence, enableFkPointers, extractBlockNames, extractBlocks, extractEnumBlocks, extractEnumNames, extractFragmentBlocks, extractModelBlocks, extractModelNames, findDbCatalogBlocks, findFkPointers, findMovedSettings, foreignKeyOf, hasBackRelation, hasConstraints, isNoLongerPublic, isOneToOne, judgeModuleResolution, kebabCase, migrationCreatedBy, minimumQuotasPerPlan, modelsKeptPastTheTenant, namedImports, parseBlockAttributes, parseEnumValues, parseFields, parseQuota, parseSchema, pascalCase, patchAppModule, patchOptionsFor, planInit, quotaKeyPattern, readEffectiveModuleResolution, relationNameOf, removeProjectKey, reportConstraints, rewriteImports, rewriteManifest, rewriteNames, rewriteSubpath, settingsWrittenTo, stripLineComment, structuralOnly, tablesAddressedBy };