@saasicat/cli 0.26.1 → 1.0.0-rc.0

package/dist/index.d.ts

@@ -497,6 +497,466 @@ declare function breaksContract(attribute: MissingBlockAttribute): boolean;
  */
 declare function checkSchema(specSchema: string, appSchema: string): SchemaCheckReport;
 
+/** Marks the block this tool appends, and lets it recognise its own work. */
+declare const CONSTRAINTS_MARKER = "-- saasicat:constraints";
+/**
+ * The migration THIS run created — the one that is in `after` and not `before`.
+ *
+ * The first version asked which directory sorts last, which is the same answer
+ * whenever the run created one and a silently wrong one when it did not: the
+ * step would then edit a stranger's migration, one already applied, and break
+ * its checksum. Taking the difference cannot confuse the two.
+ *
+ * `<timestamp>_<name>` is required, so `migration_lock.toml` and a stray
+ * scratch directory are not candidates however they sort.
+ */
+declare function migrationCreatedBy(before: readonly string[], after: readonly string[]): string | null;
+/** Whether this SQL already carries a constraints block from a previous run. */
+declare function hasConstraints(migrationSql: string): boolean;
+/**
+ * The tables a constraints statement addresses.
+ *
+ * `CREATE ... INDEX ... ON <table>` and `ALTER TABLE <table>` are the two
+ * shapes the canonical file uses; anything else is returned as addressing
+ * nothing, which keeps it.
+ */
+declare function tablesAddressedBy(statement: string): string[];
+/**
+ * The constraints that apply to tables this schema actually has.
+ *
+ * `schema migrate --fragments=03` produces a migration with the plan-version
+ * tables and nothing else, and appending the whole file would add an index on
+ * `bundle_versions` — which Prisma then fails to apply, against the shadow
+ * database, with P1014 naming a table the consumer never asked for. Found by
+ * running the command rather than by reasoning about it.
+ *
+ * Statements addressing no table at all are kept: an unrecognised shape is a
+ * reason to be conservative, not to drop a constraint.
+ */
+declare function constraintsFor(constraintsSql: string, tables: readonly string[]): string;
+/**
+ * The migration with the constraints appended, or the input unchanged when it
+ * already has them.
+ *
+ * Appended rather than merged: the statements are `CREATE UNIQUE INDEX IF NOT
+ * EXISTS` and an `ALTER TABLE ... ADD CONSTRAINT`, so they have to run after
+ * the tables exist, and Prisma writes the table creation into the same file.
+ */
+declare function appendConstraints(migrationSql: string, constraintsSql: string): string;
+/**
+ * What step 3 of `schema migrate` did — and whether step 4 may follow.
+ *
+ * It was a boolean, and the boolean conflated two states that need opposite
+ * answers: "there was nothing to append" and "appending failed". On the second
+ * one the command told the operator to add the SQL by hand *before applying
+ * it* — and then applied it three lines later, which both makes the advice
+ * unfollowable and puts the file under a recorded checksum, so editing it
+ * afterwards offers a reset. Prisma's `--create-only` exists to open exactly
+ * that window; closing it by hand was the point.
+ */
+type ConstraintsOutcome = 
+/** Written into the migration this run created. */
+'appended'
+/** The migration already carried them — a re-run. */
+ | 'already-present'
+/** No constraint addresses a table in this schema. */
+ | 'not-applicable'
+/** Prisma created no migration, so there was nothing to append to. */
+ | 'no-migration'
+/** The file could not be read or written. */
+ | 'failed';
+interface ConstraintsReport {
+    readonly outcome: ConstraintsOutcome;
+    /**
+     * Whether the command may go on to apply the migration.
+     *
+     * False only for `failed`: every other outcome leaves a migration that is
+     * complete, or none at all.
+     */
+    readonly mayApply: boolean;
+    /** What to tell the operator, in one line. */
+    readonly message: string;
+}
+/**
+ * The decision and the message together, so they cannot contradict each other.
+ *
+ * They did: the message named a window the caller had already closed. Keeping
+ * them in one function lets a test assert the invariant that broke —
+ * "before applying" appears exactly when the command will not apply.
+ */
+declare function reportConstraints(outcome: ConstraintsOutcome, context: {
+    readonly sqlPath: string;
+    readonly migration?: string | null;
+}): ConstraintsReport;
+
+/** A commented-out relation line, and what it points at. */
+interface FkPointer {
+    /** 0-based line index in the schema. */
+    readonly line: number;
+    /** The model the relation targets, as the fragment names it. */
+    readonly target: 'Tenant' | 'User';
+    /** The model the line lives in — the other side of the relation. */
+    readonly model: string;
+    /** The line as it stands, still commented. */
+    readonly text: string;
+}
+/** Every commented-out FK pointer in `schema`, with the model it sits in. */
+declare function findFkPointers(schema: string): FkPointer[];
+/** The name of a named relation (`@relation("AuditLogUser", …)`), or null. */
+declare function relationNameOf(relationAttribute: string): string | null;
+/**
+ * Whether the foreign key is unique — which makes the relation 1:1, not 1:n.
+ *
+ * `Subscription.tenantId` carries `@unique`, so a tenant has at most one
+ * subscription and the opposite field is `subscription Subscription?`, not a
+ * list. The example app writes it exactly that way. A check that only knew
+ * lists called that correct schema incomplete and told the consumer to add a
+ * second, contradictory field.
+ *
+ * Measured, because the obvious guess is wrong: `prisma validate` 6.19.3
+ * ACCEPTS `subscriptions Subscription[]` against a `@unique` foreign key. So
+ * the list is not a build break — it is worse placed than that. The generated
+ * client types the relation as a list the database can never hold more than
+ * one of, and nothing says so until someone writes code for the second row.
+ * Only the missing field is P1012.
+ */
+declare function isOneToOne(schema: string, model: string, foreignKey: string): boolean;
+/**
+ * Whether `owner` already declares the opposite side of this relation.
+ *
+ * Prisma relations have two sides. Enabling `tenant Tenant @relation(...)` on
+ * `AuditLog` without a matching field on `Tenant` produces a schema Prisma
+ * refuses with P1012 — and the first version of this did exactly that to the
+ * project's own example app.
+ *
+ * Two things are part of the question rather than details, and Prisma taught
+ * each by refusing the result:
+ *
+ *   - The relation NAME. `AuditLog.user` carries `@relation("AuditLogUser", …)`
+ *     because a model may point at `User` more than once, and an unnamed field
+ *     does not pair with it.
+ *   - The CARDINALITY. A unique foreign key makes the opposite side singular,
+ *     and a check that only knew lists reported a correct schema as broken.
+ */
+declare function hasBackRelation(schema: string, model: string, owner: string, relationName: string | null, singular?: boolean): boolean;
+interface FkModelNames {
+    /** What the app calls its tenant model, e.g. `Organization`. */
+    tenant?: string;
+    /** What the app calls its user model, e.g. `Account`. */
+    user?: string;
+}
+interface EnableFkResult {
+    readonly schema: string;
+    /** The pointers that were enabled, with the model each now names. */
+    readonly enabled: ReadonlyArray<{
+        line: number;
+        model: string;
+    }>;
+    /**
+     * Pointers left commented because the caller did not name that model.
+     *
+     * Reported rather than dropped: a schema half-wired for referential
+     * integrity is worse than one that is not, because it looks finished.
+     */
+    readonly skipped: ReadonlyArray<{
+        line: number;
+        target: string;
+    }>;
+    /**
+     * Pointers left commented because the app model has no opposite field, with
+     * the line to add.
+     *
+     * Separate from `skipped`, because the answer is different: those need a
+     * flag, these need one line in a model the tool must not edit on its own.
+     */
+    readonly needsBackRelation: ReadonlyArray<{
+        line: number;
+        owner: string;
+        suggestion: string;
+    }>;
+}
+/**
+ * Uncomments the FK pointers and renames their target to the app's model.
+ *
+ * Only for targets the caller actually named. `--tenant-model` without
+ * `--user-model` enables the tenant relations and leaves the user ones
+ * commented, which is a real configuration: not every app has a `User` the
+ * audit log should point at.
+ */
+declare function enableFkPointers(schema: string, models: FkModelNames): EnableFkResult;
+/** The scalar this relation is built on — `fields: [tenantId]`. */
+declare function foreignKeyOf(relationAttribute: string): string | null;
+/**
+ * Refuses a model name the schema does not define.
+ *
+ * Without this the command would produce a schema that does not validate, and
+ * the error would come from Prisma, about a line the consumer did not write.
+ */
+declare function assertModelsExist(declaredModels: readonly string[], models: FkModelNames): void;
+
+/** 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`. */
+    appName?: string;
+    /** Admin API prefix, e.g. `/api/v1/admin`. */
+    apiBase?: string;
+    /**
+     * Countable dimensions, as `key:Model` — `notes:Note` means a quota
+     * `notes` counted with `prisma.note.count()`.
+     */
+    quotas?: readonly string[];
+    /** Skip the password hasher when the app already has one. */
+    skipHasher?: boolean;
+}
+/** One file the generator will write. */
+interface PlannedFile {
+    /** Path relative to the app root. */
+    readonly path: string;
+    /** Template path relative to `templates/init/`, without `.tpl`. */
+    readonly template: string;
+    /** Substitutions for this file, on top of the shared ones. */
+    readonly tokens: Readonly<Record<string, string>>;
+}
+interface InitPlan {
+    readonly files: readonly PlannedFile[];
+    readonly tokens: Readonly<Record<string, string>>;
+    /**
+     * The quota providers `app.module.ts` has to register, with the file each
+     * one was written to.
+     *
+     * The path is carried rather than re-derived. It was re-derived, from the
+     * class name, while the file was named from the quota key — two spellings
+     * of one name that agree for `notes` and part company for `apiCalls`:
+     * `apicalls-quota.provider.ts` written, `./saas/api-calls-quota.provider`
+     * imported, TS2307. The same shape as the persistence import a round
+     * earlier: a fix in the plan that its caller did not follow.
+     */
+    readonly quotaProviders: readonly QuotaProviderFile[];
+    /** The hasher class, or null when the caller brings their own. */
+    readonly hasherClass: string | null;
+}
+/** A parsed `--quota=key:Model` entry. */
+interface QuotaProviderFile {
+    /** The class the module registers. */
+    readonly className: string;
+    /** Where the plan writes it, relative to the project root. */
+    readonly path: string;
+}
+interface QuotaSpec {
+    readonly key: string;
+    /** The Prisma delegate to count, e.g. `note`. */
+    readonly model: string;
+}
+/**
+ * Reads `key:Model`, or `key` when the model matches the key.
+ *
+ * The model is lower-camelised because that is what Prisma calls its delegate:
+ * a `Note` model is `prisma.note`, a `TeamMember` is `prisma.teamMember`. A
+ * generated file that named the model instead would not compile, and the
+ * failure would look like a schema problem.
+ */
+declare function parseQuota(spec: string): QuotaSpec;
+/** `notes` → `Notes`, `team-members` → `TeamMembers`. */
+declare function pascalCase(value: string): string;
+/**
+ * Everything the generator will do, as data.
+ *
+ * The quota block in the YAML is rendered here rather than in the template
+ * because it varies in LENGTH — a template can substitute a value, not repeat
+ * a section, and a template language that could would be a second thing to
+ * learn for the one file that needs it.
+ */
+declare function planInit(options: InitOptions): InitPlan;
+/** `NotesApp` → `notes-app`. */
+declare const kebabCase: (value: string) => string;
+/** Replaces `__TOKEN__` with its value; an unknown token is left visible. */
+declare function applyTokens(content: string, tokens: Record<string, string>): string;
+/**
+ * The patch options a plan implies.
+ *
+ * Here rather than in `bin/saasicat.js`, and that is the point of the move:
+ * both leftovers of the first review round were in this derivation, where
+ * `plan.ts` and `patchAppModule` were each tested and the step between them was
+ * not. `persistenceImport` hung on `hasherClass` while the plan had started
+ * writing the bundle in both cases, so `--skip-hasher` produced an app whose
+ * persistence file existed and was never imported.
+ *
+ * Read off the plan's own file list, so a file that is generated is a file that
+ * is wired, and the two cannot drift again.
+ */
+declare function patchOptionsFor(plan: InitPlan): PatchOptionsFromPlan;
+/** What `patchAppModule` takes, derived from a plan. */
+interface PatchOptionsFromPlan {
+    persistenceImport: string | null;
+    adminModule: {
+        className: string;
+        importPath: string;
+    };
+    quotaProviders: Array<{
+        className: string;
+        importPath: string;
+    }>;
+    registry: {
+        constName: string;
+        importPath: string;
+    };
+}
+
+/** The pattern `plan-catalog.schema.json` puts on `projectKey`. */
+declare function projectKeyPattern(): 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. */
+declare function minimumQuotasPerPlan(): number;
+/**
+ * Refuses a project key the platform will refuse, while nothing is written yet.
+ *
+ * The message carries the pattern rather than a prose paraphrase, because the
+ * paraphrase is what goes stale.
+ */
+declare function assertValidProjectKey(projectKey: string): void;
+/** The same, for a quota key. `additionalProperties: false` makes it a hard rule. */
+declare function assertValidQuotaKey(quotaKey: string): void;
+
+/** One entry of the move table: where a file was, and where it went. */
+interface MoveTable {
+    readonly moves: Readonly<Record<string, string>>;
+    /**
+     * Prefixes that left the package entirely. The value is a full specifier
+     * — `@saasicat/ui-vue-tenant/` — and is emitted verbatim.
+     */
+    readonly packages?: Readonly<Record<string, string>>;
+    /**
+     * Directories whose files left the surface as a whole — the page-private
+     * parts under `pages-standard/<page>/` that became `internal/<page>/`.
+     */
+    readonly moveDirectories?: Readonly<Record<string, string>>;
+}
+/**
+ * Old subpath → new subpath, derived from the move table.
+ *
+ * Both spellings of a page that moved are mapped, because both were reachable:
+ * `pages/AdminLayout.vue` and `pages-standard/AdminLayout.vue` named one file.
+ */
+declare function buildImportMap(table: MoveTable): Map<string, string>;
+/**
+ * What a subpath becomes, or null when it is already right.
+ *
+ * A `pages-standard/` path with no entry in the table is a page that did not
+ * move: it keeps its name under the surviving alias.
+ */
+declare function rewriteSubpath(map: ReadonlyMap<string, string>, subpath: string): string | null;
+/**
+ * Whether a subpath was public before and is not any more.
+ *
+ * Reported rather than rewritten: it moved into `features/` or `internal/`,
+ * which the 1.0 surface does not publish, so there is no destination to point
+ * at. Leaving it silently would hand the consumer a build error with no
+ * explanation of what happened.
+ */
+declare function isNoLongerPublic(map: ReadonlyMap<string, string>, subpath: string): boolean;
+/** Every `@saasicat/ui-vue/<subpath>` occurrence in a source text. */
+declare const UI_VUE_SPECIFIER: RegExp;
+interface RewriteResult {
+    readonly text: string;
+    readonly rewritten: number;
+    /** Subpaths that lost their export, with how often each appeared. */
+    readonly unmapped: ReadonlyMap<string, number>;
+}
+/** Applies the map to one file's text. */
+declare function rewriteImports(text: string, map: ReadonlyMap<string, string>): RewriteResult;
+
+/** One entry of the rename table. */
+interface RenameTable {
+    /** An identifier stem, matched anywhere in an identifier, and its replacement. */
+    readonly identifierStems: Readonly<Record<string, string>>;
+    /** A registry-key prefix (or a whole key) inside a string literal, and its replacement. */
+    readonly registryKeys: Readonly<Record<string, string>>;
+    /** Per import specifier: a name that means something different per entry. */
+    readonly entryTokens: Readonly<Record<string, Readonly<Record<string, string>>>>;
+    /** A module specifier prefix and its replacement. */
+    readonly subpaths: Readonly<Record<string, string>>;
+}
+interface RenameResult {
+    readonly text: string;
+    readonly rewritten: number;
+    /**
+     * Names the table knows only per entry, imported from somewhere the table
+     * does not cover. Reported rather than guessed: which registry the
+     * consumer meant is not in the text.
+     */
+    readonly ambiguous: readonly string[];
+}
+/**
+ * The specifier and the bound names of every `import { … } from '…'`.
+ *
+ * Read backwards from each `from`, one character at a time, instead of with
+ * one regular expression over the statement: `\{([^}]*)\}\s+from` and its
+ * siblings backtrack quadratically on a file full of `import {{`, and the
+ * file is a consumer's — whatever they wrote, this must finish.
+ */
+declare function namedImports(text: string): Array<{
+    names: string[];
+    specifier: string;
+}>;
+/** Applies the table to one file's text. Idempotent: a second run changes nothing. */
+declare function rewriteNames(text: string, table: RenameTable): RenameResult;
+
+interface PatchAppModuleOptions {
+    /** Import specifier for the persistence bundle, or null when not generated. */
+    persistenceImport: string | null;
+    /** The app's admin module class and the file it lives in. */
+    adminModule: {
+        className: string;
+        importPath: string;
+    };
+    /** Quota provider classes and where they came from. */
+    quotaProviders: ReadonlyArray<{
+        className: string;
+        importPath: string;
+    }>;
+    /** The feature-UI registry constant and its file. */
+    registry: {
+        constName: string;
+        importPath: string;
+    };
+}
+interface PatchResult {
+    /** The patched source, or the input unchanged when nothing was done. */
+    readonly source: string;
+    /** What happened, for the command to print. */
+    readonly status: 'patched' | 'already-wired' | 'declined';
+    /** Why it declined, and what to do instead. Empty otherwise. */
+    readonly reason: string;
+    /** The block to paste by hand when it declined. */
+    readonly manualBlock: string;
+}
+/**
+ * Adds the platform to an `@Module({ imports: [...] })` decorator.
+ *
+ * Returns `declined` rather than guessing when the shape is not the one this
+ * can edit safely: no `@Module`, no `imports` array, or a file that already
+ * mentions the marker.
+ */
+declare function patchAppModule(source: string, options: PatchAppModuleOptions): PatchResult;
+/**
+ * The `APP_FILTER` provider, as text.
+ *
+ * Not inserted automatically: `providers` is where an application keeps its own
+ * wiring, and an entry added into the middle of it is the edit most likely to
+ * land somewhere surprising. Printed instead, with the reason.
+ */
+declare const LIMIT_FILTER_PROVIDER = "{ provide: APP_FILTER, useClass: LimitExceededFilter }";
+/**
+ * The imports that provider needs, printed with it rather than inserted.
+ *
+ * They are not in `renderImports` on purpose: the file would import two symbols
+ * it does not use, which is a lint error in the first project this lands in.
+ */
+declare const LIMIT_FILTER_IMPORTS: string;
+
 interface CliContextModuleOptions {
     config: CliContextConfig;
     userPort: ProviderSpec<UserPort>;
@@ -687,4 +1147,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, type CheckSeverity, type CliContextConfig, CliContextModule, type CliContextModuleOptions, CliContextService, CliError, type CliIdentity, DEFAULT_MANIFEST_CHECKS, DOCTOR_CHECKS_TOKEN, DiscoveryCommands, DiscoveryScanCommand, DiscoverySnapshotDoctorCheck, type DoctorCheck, type DoctorCheckResult, DoctorCommands, DoctorFlow, type DoctorReport, type FieldMismatch, type FieldMismatchReason, type FieldSignature, MANIFEST_ACCESS_PORT_TOKEN, MANIFEST_CHECKS_TOKEN, type ManifestCheck, ManifestCheckCommand, type ManifestCheckReport, type ManifestCheckResult, ManifestCliFlow, ManifestCommands, type ManifestDiff, ManifestDumpCommand, ManifestHashCommand, ManifestValidateCommand, MfaSetupFlow, type MfaSetupOptions, type MfaSetupResult, type MissingBlockAttribute, type MissingEnumValue, type MissingField, PLATFORM_DOCTOR_CHECK_PROVIDERS, type ParsedSchema, PlanCatalogDoctorCheck, type SchemaCheckReport, USER_MANAGEMENT_PORT_TOKEN, USER_PORT_TOKEN, UserCommands, UserPortDoctorCheck, WhoAmIFlow, type WhoAmIResult, applyFragmentBlocks, blankStringLiterals, blockBodyLines, breaksContract, checkSchema, extractBlockNames, extractBlocks, extractModelBlocks, extractModelNames, parseBlockAttributes, parseEnumValues, parseFields, parseSchema, stripLineComment, structuralOnly };
+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 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, ManifestValidateCommand, MfaSetupFlow, type MfaSetupOptions, type MfaSetupResult, type MissingBlockAttribute, type MissingEnumValue, type MissingField, 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, extractModelBlocks, extractModelNames, findFkPointers, foreignKeyOf, hasBackRelation, hasConstraints, isNoLongerPublic, isOneToOne, kebabCase, migrationCreatedBy, minimumQuotasPerPlan, namedImports, parseBlockAttributes, parseEnumValues, parseFields, parseQuota, parseSchema, pascalCase, patchAppModule, patchOptionsFor, planInit, projectKeyPattern, quotaKeyPattern, relationNameOf, reportConstraints, rewriteImports, rewriteNames, rewriteSubpath, stripLineComment, structuralOnly, tablesAddressedBy };