@rebasepro/server-postgres 0.13.1-canary.gef9608c → 0.14.0

package/dist/schema/auth-users-columns.d.ts

@@ -0,0 +1,97 @@
+/**
+ * The one description of what an auth user table's columns must be.
+ *
+ * ## Why this exists
+ *
+ * Three different code paths create `rebase.users`, and before this module they
+ * disagreed about it:
+ *
+ * | column           | `db push` (generator) | `ensureAuthTablesExist` | `ensureCollectionTables` |
+ * |------------------|-----------------------|-------------------------|--------------------------|
+ * | `email`          | `TEXT UNIQUE NOT NULL`| `TEXT NOT NULL` + CHECK | `TEXT` (nullable)        |
+ * | `roles`          | `TEXT[]`              | `NOT NULL DEFAULT '{}'` | nullable, no default     |
+ * | `email_verified` | `BOOLEAN`             | `NOT NULL DEFAULT FALSE`| nullable                 |
+ * | `created_at`     | `DEFAULT now()`       | `NOT NULL DEFAULT NOW()`| no default               |
+ *
+ * They are all `CREATE TABLE IF NOT EXISTS` / `ADD COLUMN IF NOT EXISTS`, so
+ * whichever ran first decided the table and the other two silently no-op'd.
+ * Boot order therefore chose the constraints: a managed deploy (collection
+ * tables first) got a users table whose `email` was nullable and whose
+ * `email_verified` had no default, while the same project pushed from a
+ * checkout got the strict one. In the same table, `is_anonymous` came out
+ * `NOT NULL DEFAULT false` — because *that* column existed in only one of the
+ * three lists, so its owner's definition won by default.
+ *
+ * A second consequence was drift in the other direction. The scaffold's
+ * `users.ts` describes 12 columns; auth needs 14. `db push` is declarative and
+ * builds its desired state from the collection alone, so the two columns only
+ * auth knows about (`is_anonymous`, `tokens_valid_after`) read as unmanaged
+ * drift, and a push run after the server had booted once planned to DROP them.
+ *
+ * Both problems are the same problem: no single place said what this table is.
+ * This is that place. Every creator asks here first and only then falls back to
+ * the collection's own property definitions, so a column auth owns has one
+ * definition regardless of who gets there first, and a column the developer
+ * added to their users collection still behaves like any other field.
+ *
+ * ## What belongs here
+ *
+ * Only columns the auth services read or write. A developer's own additions to
+ * their users collection (`bio`, `stripe_customer_id`) are ordinary columns and
+ * must NOT be listed — they are generated from the collection like every other
+ * field, and listing them here would freeze a user's schema.
+ *
+ * `id` is deliberately absent: its type comes from the collection's id property
+ * (uuid / increment / text) and each creator already derives it.
+ *
+ * Keep in step with {@link AUTH_SCHEMA_VERSION} when a change here makes an
+ * older runtime unable to work against a migrated table.
+ */
+/**
+ * A column auth owns.
+ *
+ * Structured rather than one SQL string because the same facts are needed in
+ * three grammars — a `CREATE TABLE` column list, an `ADD COLUMN IF NOT EXISTS`,
+ * and a pair of `ALTER COLUMN … SET DEFAULT` / `SET NOT NULL` reconciles for a
+ * table that already exists with the wrong shape. Parsing a string back apart
+ * for the third of those is how the copies drifted in the first place.
+ */
+export interface AuthUsersColumn {
+    /** Physical column name. */
+    column: string;
+    /** Postgres type. */
+    type: string;
+    /** Default expression, verbatim, or absent for no default. */
+    default?: string;
+    /** Whether the column is NOT NULL. */
+    notNull?: boolean;
+}
+/**
+ * `email` is NOT NULL on purpose, and the anonymous sign-in route depends on it
+ * — it synthesizes `anon_<32 hex>@anonymous.local` rather than inserting NULL.
+ * The 320-char bound (RFC 5321) is a CHECK rather than a `VARCHAR(n)`, added
+ * separately by `ensureAuthTablesExist` so it can be `NOT VALID` on an adopted
+ * table that already holds a longer row.
+ */
+export declare const AUTH_USERS_COLUMNS: readonly AuthUsersColumn[];
+/** Type + inline constraints, as they appear after the column name. */
+export declare function authUsersColumnSql(spec: AuthUsersColumn): string;
+/**
+ * The auth-owned definition for a physical column name, or `undefined` when
+ * auth does not own it.
+ *
+ * Callers pass the RESOLVED column name (after `columnName` mapping), because
+ * that is the only name the three creators agree on: the scaffold's users
+ * collection spells the property `displayName` and the column `display_name`.
+ */
+export declare function authUsersColumnDefinition(column: string): string | undefined;
+/**
+ * Whether a collection is an auth collection, i.e. whether the definitions in
+ * this module apply to its table at all.
+ *
+ * Duplicated in shape from `@rebasepro/common`'s policy defaults on purpose:
+ * that one takes a `CollectionConfig`, this one is called from DDL code paths
+ * that hold looser objects, and both spellings must accept `auth: true` as well
+ * as `auth: { enabled: true }`.
+ */
+export declare function isAuthCollection(collection: unknown): boolean;

package/dist/schema/doctor-policy-checks.d.ts

@@ -0,0 +1,28 @@
+/**
+ * What the RLS checks concluded.
+ *
+ * `unchecked` exists because "we could not look" and "we looked and it is fine"
+ * used to be reported identically: a collections path that did not resolve made
+ * the loader return `[]` (it warns, it does not throw), `checkPolicyDrift`
+ * early-returned an empty diff, and the gate printed
+ * `✓ RLS policies match your collections` having compared zero policies against
+ * zero collections. Any exception at all — a collection file that throws on
+ * import, a `pg_policies` read the CI role is not granted, a connection reset —
+ * did the same thing through a `warn`, and exited 0.
+ */
+export type PolicyCheckStatus = "ok" | "problems" | "unchecked";
+/**
+ * The exit code for `rebase doctor --policies`.
+ *
+ * A gate that could not run has not passed. Only a completed, clean check
+ * exits 0 — anything else, including "we never opened a connection", is a
+ * failure, or the flag certifies a database nobody looked at.
+ */
+export declare function exitCodeForPolicyGate(status: PolicyCheckStatus): 0 | 1;
+/**
+ * Policies actually deployed vs the ones the collections describe, plus policy
+ * roles this server could never satisfy.
+ *
+ * Never reports `ok` for work it did not do — see {@link PolicyCheckStatus}.
+ */
+export declare function runPolicyChecks(collectionsPath: string, databaseUrl?: string): Promise<PolicyCheckStatus>;

package/dist/schema/doctor.d.ts

@@ -2,7 +2,7 @@ import { CollectionConfig, Property } from "@rebasepro/types";
 export type IssueSeverity = "error" | "warning" | "info";
 export interface DoctorIssue {
     severity: IssueSeverity;
-    category: "missing_table" | "missing_column" | "type_mismatch" | "missing_constraint" | "schema_stale" | "missing_enum" | "enum_value_mismatch" | "missing_foreign_key" | "sdk_stale" | "sdk_not_generated";
+    category: "missing_table" | "missing_column" | "type_mismatch" | "missing_constraint" | "schema_stale" | "missing_enum" | "enum_value_mismatch" | "missing_foreign_key" | "sdk_stale" | "sdk_not_generated" | "sdk_ungeneratable";
     table?: string;
     column?: string;
     expected?: string;
@@ -10,21 +10,46 @@ export interface DoctorIssue {
     message: string;
     fix: string;
 }
+export interface DoctorPhase {
+    passed: boolean;
+    issues: DoctorIssue[];
+    /**
+     * Why this phase never ran, when it did not.
+     *
+     * A check that did not happen is a third state, not a passing one. While a
+     * skipped phase initialised to `{ passed: true, issues: [] }` it rendered as
+     * `✅ Collections → Database: In sync` and counted towards
+     * `✓ All schemas are in sync!` — so a project whose connection string was
+     * spelled `POSTGRES_URL`, or a CI job that never exported one, got two green
+     * ticks and exit 0 against a database with no tables in it.
+     */
+    skipped?: string;
+    /**
+     * Why this phase had nothing to compare against, when it had nothing.
+     *
+     * Distinct from `skipped`, which means "the check could not run, and that
+     * is probably worth fixing". This one means "the artifact is optional and
+     * you have not asked for it": no drift is possible, so the run is still a
+     * clean bill of health.
+     *
+     * It exists because the alternative was a contradiction. The typed-SDK
+     * phase returned `{ passed: true }` when `generated/sdk/database.types.ts`
+     * did not exist, so a fresh project's report read
+     * `✅ Collections → SDK Types: In sync` directly above
+     * `ℹ Typed SDK not generated (optional).` — one line calling a file
+     * synchronised and the next saying it is absent. "In sync" is a claim about
+     * a comparison, and no comparison happened.
+     */
+    notApplicable?: string;
+}
 export interface DoctorReport {
-    collectionsToSchema: {
-        passed: boolean;
-        issues: DoctorIssue[];
-    };
-    collectionsToSdk: {
-        passed: boolean;
-        issues: DoctorIssue[];
-    };
-    schemaToDatabase: {
-        passed: boolean;
-        issues: DoctorIssue[];
-    };
+    collectionsToSchema: DoctorPhase;
+    collectionsToSdk: DoctorPhase;
+    schemaToDatabase: DoctorPhase;
     summary: {
         passed: number;
+        skipped: number;
+        notApplicable: number;
         warnings: number;
         errors: number;
     };
@@ -37,18 +62,9 @@ export declare function getExpectedColumnType(prop: Property): string | null;
  * wrong thing.
  */
 export declare function loadCollections(collectionsPath: string): Promise<CollectionConfig[]>;
-export declare function checkCollectionsVsSchema(collections: CollectionConfig[], schemaFilePath: string): Promise<{
-    passed: boolean;
-    issues: DoctorIssue[];
-}>;
-export declare function checkCollectionsVsSdk(collections: CollectionConfig[], sdkFilePath: string): Promise<{
-    passed: boolean;
-    issues: DoctorIssue[];
-}>;
-export declare function checkCollectionsVsDatabase(collections: CollectionConfig[], databaseUrl: string): Promise<{
-    passed: boolean;
-    issues: DoctorIssue[];
-}>;
+export declare function checkCollectionsVsSchema(collections: CollectionConfig[], schemaFilePath: string): Promise<DoctorPhase>;
+export declare function checkCollectionsVsSdk(collections: CollectionConfig[], sdkFilePath: string): Promise<DoctorPhase>;
+export declare function checkCollectionsVsDatabase(collections: CollectionConfig[], databaseUrl: string): Promise<DoctorPhase>;
 export declare function renderReport(report: DoctorReport): void;
 export declare function runDoctor(options: {
     collectionsPath: string;

package/dist/schema/ensure-collection-policies.d.ts

@@ -43,18 +43,42 @@ export interface PolicyEnsureResult {
         table: string;
         reason: string;
     }[];
-    /** Tables whose RLS could not be fully applied (fail closed). */
+    /**
+     * Tables that have RLS on but did not get every policy. They deny — RLS
+     * with no matching policy is deny-all — so they are safe but not servable.
+     */
     failures: {
         table: string;
         error: string;
     }[];
+    /**
+     * Tables RLS could not be enabled on, whose DML grant was withdrawn instead.
+     *
+     * This state had no name, and that was the bug: `ENABLE ROW LEVEL SECURITY`
+     * failing was recorded as a `failure` and reported with the same "it stays
+     * locked (denies)" wording as a failed policy — but the two are opposites.
+     * A policy statement failing leaves RLS on and the table denying. `enableRls`
+     * failing leaves RLS *off*, and the schema-wide grant to the user role has
+     * already been made by `ensureRlsEnforcement`, so the table is readable and
+     * writable by every authenticated request with no row filtering at all.
+     */
+    unsecured: {
+        table: string;
+        error: string;
+        grantWithdrawn: boolean;
+    }[];
+    /**
+     * Generated policies removed because no current rule produces them.
+     *
+     * A policy's name embeds a hash of the rule's semantics, so editing a rule
+     * does not update a policy — it creates a new one and abandons the old.
+     * Postgres ORs permissive policies, so the abandoned one keeps granting:
+     * a `USING (true)` tightened to an owner check went on admitting everyone,
+     * forever, while the deploy logged success.
+     *
+     * `db push` reconciles this, and cannot reach a managed tenant's in-cluster
+     * database — which is the reason this module exists. So boot has to do it.
+     */
+    orphansDropped: number;
 }
-/**
- * Bring the declared collections' RLS policies up to date. Returns what it did.
- *
- * Only tables that already exist are touched: the boot-time table creator runs
- * first, so anything still missing is a table this additive path is not allowed
- * to create (a junction, or a relation left to a migration). Enabling RLS on a
- * non-existent table would error, so those are recorded as skipped, not failed.
- */
 export declare function ensureCollectionPolicies(client: Queryable, collections: CollectionConfig[], log?: (message: string) => void): Promise<PolicyEnsureResult>;

package/dist/schema/ensure-collection-tables.d.ts

@@ -54,9 +54,17 @@ export interface ExistingSchema {
      * constraint that then fails harmlessly as a duplicate.
      */
     constraints?: Set<string>;
+    /**
+     * `schema.table.column` → that column's comment, for the columns that have
+     * one. This is where a generated search column's fingerprint lives, so it
+     * is the only evidence that a `search` block has changed since the column
+     * was built. Absent is read as "no column is stamped", which plans a stamp
+     * and reports nothing as drifted.
+     */
+    columnComments?: Map<string, string>;
 }
 export interface EnsureAction {
-    kind: "create-enum" | "create-table" | "add-column" | "add-constraint" | "rename-column";
+    kind: "create-enum" | "create-table" | "add-column" | "add-constraint" | "rename-column" | "create-extension" | "create-function" | "create-index" | "comment-column";
     /** Qualified target, for logging: `public.posts` or `public.posts.title`. */
     target: string;
     sql: string;
@@ -76,6 +84,49 @@ export interface EnsurePlan {
      * resolving to nothing — which is indistinguishable from having no data.
      */
     legacyForeignKeys: LegacyForeignKey[];
+    /**
+     * Generated search columns whose `search` block has changed since they were
+     * built. Reported, never planned into `actions` — see
+     * {@link SearchColumnDrift} for why applying it is not this path's call.
+     */
+    searchDrift: SearchColumnDrift[];
+    /**
+     * Generated search columns that exist but carry no fingerprint — created
+     * before this check existed, or by `search.sql` on an older CLI. The plan
+     * stamps them so the *next* change is detectable; whether they match the
+     * current block cannot be known, which is what the caller reports.
+     */
+    searchAdopted: {
+        table: string;
+        column: string;
+    }[];
+}
+/**
+ * A generated search column built from a `search` block that has since changed.
+ *
+ * Reported instead of applied because the two ways to apply it are both worse
+ * than stopping. `ALTER COLUMN … SET EXPRESSION` exists only on PG17+ and
+ * rewrites the table either way; `DROP COLUMN` + `ADD COLUMN` rewrites it under
+ * an ACCESS EXCLUSIVE lock and rebuilds the GIN index. This module runs
+ * unattended against live customer data with nobody reading a diff — the same
+ * reason it withholds `SET NOT NULL` from an adopted table — so a multi-minute
+ * outage is not a decision it may take on its own.
+ *
+ * Not applying it silently is not an option either: that is the bug this
+ * detection exists for. A collection that added a field, flipped `unaccent` or
+ * raised a weight kept indexing the *old* set forever, and the only symptom was
+ * searches returning nothing for content plainly in the row.
+ */
+export interface SearchColumnDrift {
+    /** `schema.table`. */
+    table: string;
+    column: string;
+    /** The fingerprint recorded on the column. */
+    found: string;
+    /** The fingerprint the current `search` block computes. */
+    expected: string;
+    /** The statements that would rebuild the column, for the operator to run. */
+    rebuild: string[];
 }
 /** A relation column whose old and new spellings both plausibly apply. */
 export interface LegacyForeignKey {
@@ -88,14 +139,17 @@ export interface LegacyForeignKey {
 }
 export interface EnsureOutcome extends EnsurePlan {
     /**
-     * Constraints that could not be added — always non-fatal.
+     * Actions that could not be applied and are non-fatal by nature.
      *
-     * A foreign key can only fail on data that already violates it, and the
-     * column it would police exists either way, so the collection still serves.
-     * Refusing to boot over one would turn a pre-existing data problem into an
-     * outage. Reported loudly instead.
+     * Two kinds qualify. A foreign key can only fail on data that already
+     * violates it, and the column it would police exists either way, so the
+     * collection still serves; refusing to boot over one would turn a
+     * pre-existing data problem into an outage. A column comment is the search
+     * fingerprint, which needs table ownership — losing it costs drift
+     * detection on the next boot, not the deployment. Both are reported loudly.
      */
     failures: {
+        kind: EnsureAction["kind"];
         target: string;
         error: string;
     }[];

package/dist/schema/generate-drizzle-schema-logic.d.ts

@@ -1,2 +1,10 @@
-import { CollectionConfig } from "@rebasepro/types";
+import { CollectionConfig, Property } from "@rebasepro/types";
+/**
+ * The Drizzle column declaration a property compiles to, or `null` when the
+ * property puts no column on *this* table (an inverse relation, whose column
+ * lives on the target). Exported so it can be checked against its DDL twin
+ * `getSqlColumnType` directly — the two disagreeing is what left `geopoint`
+ * with a database column and no Drizzle key.
+ */
+export declare const getDrizzleColumn: (propName: string, prop: Property, collection: CollectionConfig, collections: CollectionConfig[]) => string | null;
 export declare const generateSchema: (allCollections: CollectionConfig[], stripPolicies?: boolean) => Promise<string>;

package/dist/schema/generate-postgres-ddl-logic.d.ts

@@ -29,8 +29,56 @@ export declare const generatePolicyStatements: (collection: CollectionConfig, ru
  */
 export declare const quoteSqlLiteral: (value: string) => string;
 export declare const getSqlColumnType: (propName: string, prop: Property, collection: CollectionConfig, collections: CollectionConfig[]) => string;
+/**
+ * Everything a `search` block needs, as a file Rebase applies itself.
+ *
+ * Search is the one part of the schema Atlas does not own. Two independent
+ * reasons, and either alone would be enough:
+ *
+ * 1. Its free tier refuses to *parse* a desired-state file that so much as
+ *    contains a function — "functions and procedures are available to
+ *    logged-in users only". A generated `tsvector` column cannot avoid one:
+ *    `unaccent` is STABLE and jsonb flattening needs a set-returning function,
+ *    so both have to be wrapped in an IMMUTABLE helper to be legal in a
+ *    generated column at all.
+ * 2. Even with the file accepted, Atlas *wipes* the dev database it diffs
+ *    against, so a helper seeded there beforehand is gone by the time the plan
+ *    is analysed. There is no hook to reinstate it.
+ *
+ * So the column, its index and its helpers are excluded from Atlas's view
+ * (`searchExcludePatterns`) and applied from here — the same arrangement the
+ * RLS policies already use, and for the same underlying reason.
+ *
+ * Ordered as it must run: extensions, then helpers, then the column whose
+ * expression calls them, then the index over that column. Every statement is
+ * `IF NOT EXISTS` / `OR REPLACE`, because this is replayed on every push and
+ * appended to migrations that run against databases at any stage of their
+ * life. Empty when nothing opted in — the caller writes no file then.
+ *
+ * The leading half — extensions and helpers, without the table-shaped
+ * statements — is available on its own as {@link searchPrerequisiteStatements},
+ * for the dev database Atlas analyses plans against. That database has none of
+ * the project's tables, so it wants the functions and nothing else.
+ */
+export declare const searchPrerequisiteStatements: (allCollections: CollectionConfig[]) => string[];
+export declare const generatePostgresSearchDdl: (allCollections: CollectionConfig[]) => string;
+/**
+ * Glob patterns telling Atlas to leave the search column and its index alone.
+ *
+ * Without these, a desired state that omits search reads to Atlas as an
+ * instruction to drop the column — taking the index and the whole search
+ * feature with it on the next push.
+ *
+ * Fully qualified, `schema.table.object`, matching the include list. The
+ * two-part form is what Atlas wants when the connection URL scopes it to one
+ * schema and is *silently ignored* otherwise: it reads `posts.search_vector`
+ * as a table named `search_vector` in a schema named `posts`, matches nothing,
+ * and reports no error for the pattern that never fired.
+ */
+export declare const searchExcludePatterns: (allCollections: CollectionConfig[]) => string[];
 export declare const generatePostgresDdl: (allCollections: CollectionConfig[], options?: {
     includePolicies?: boolean;
+    includeSearch?: boolean;
 }) => Promise<string>;
 /** The RLS statements one declared collection's table needs, ready to run. */
 /**

package/dist/schema/introspect-db-inference.d.ts

@@ -2,4 +2,11 @@ export interface InferenceResult {
     propType?: string;
     extra?: string;
 }
-export declare function inferPropertyFromData(columnName: string, pgDataType: string, currentPropType: string, sampleValues: unknown[], isPk: boolean): InferenceResult;
+export declare function inferPropertyFromData(columnName: string, pgDataType: string, currentPropType: string, sampleValues: unknown[], isPk: boolean, 
+/**
+ * False when generating for a project without `@rebasepro/admin-types`, where
+ * `BaseProperty` declares no `admin` field and the block below would not
+ * compile. The type-level inferences (`propType`, `url`, `storage`) are
+ * unaffected — only the form-widget hints are dropped.
+ */
+emitAdmin?: boolean): InferenceResult;

package/dist/schema/introspect-db-logic.d.ts

@@ -177,10 +177,59 @@ export interface GeneratedFile {
  * have no database to read constraints or row counts from, and they must keep
  * producing a valid collection.
  */
+/**
+ * Which `defineCollection` — if any — the project being generated into can import.
+ *
+ * A bare `const x: PostgresCollectionConfig = { … }` annotation widens `properties`
+ * to `Record<string, …>`, and every key-shaped field in the admin block —
+ * `titleProperty`, `sort`, `propertiesOrder`, `listProperties`, `fixedFilter` — is
+ * derived from those keys. Annotated, they accept any string: introspection was
+ * emitting a `propertiesOrder` array that nothing checked, so renaming a column and
+ * re-introspecting left a stale key that compiled silently. `defineCollection` is
+ * the identity function whose `const P` type parameter keeps the keys literal, which
+ * is what turns that checking on.
+ *
+ * There are two of them and they are not interchangeable:
+ *
+ * - `admin-types` — `@rebasepro/admin-types`. Its index side-effect-imports
+ *   `augment.ts`, so importing it is also what *declares* the `admin` block. Only a
+ *   project that depends on the package can resolve it.
+ * - `common` — `@rebasepro/common`. Same key inference, no admin surface, no React
+ *   anywhere in its graph (`scripts/headless-guard` lists it as core). This is the
+ *   headless flavour.
+ * - `annotation` — neither package is declared, so neither import would resolve and
+ *   the old annotation is the only honest thing to emit. Projects scaffolded before
+ *   `@rebasepro/common` joined the headless config package land here.
+ *
+ * The last two emit **no admin block, on the collection or on any property**. That is
+ * not a downgrade: `@rebasepro/types` declares no `admin` field at all, so the block
+ * introspection used to emit was a type error in every headless project it was
+ * written into. See `packages/admin-types/src/augment.ts`.
+ */
+export type CollectionBuilder = "admin-types" | "common" | "annotation";
+/**
+ * The package specifiers the generated files name, spelled once.
+ *
+ * Written as constants rather than inline in the import templates below because
+ * `scripts/headless-guard/check-types.mjs` scans core sources for `from
+ * "@rebasepro/admin-types"` and cannot tell a real import from one this module
+ * *writes*. It is right to be that blunt — the guard's whole value is that it
+ * cannot be reasoned around — so the string simply never appears in that shape
+ * here. Inlining them back into the templates re-breaks `check:types-headless`.
+ */
+export declare const ADMIN_TYPES_PACKAGE = "@rebasepro/admin-types";
+export declare const COMMON_PACKAGE = "@rebasepro/common";
+export declare const TYPES_PACKAGE = "@rebasepro/types";
 export interface GenerationContext {
     metadata?: SchemaMetadata;
     classifications?: Map<string, TableClassification>;
     checkFacts?: CheckFactsByTable;
+    /**
+     * Defaults to `admin-types`, which is what the generator has always emitted.
+     * The CLI never relies on the default — `introspect-db.ts` detects the flavour
+     * from the target project and passes it. See `detectCollectionBuilder`.
+     */
+    builder?: CollectionBuilder;
 }
 /**
  * Generate the full TypeScript file content for a single collection.

package/dist/schema/introspect-db-project.d.ts

@@ -0,0 +1,21 @@
+import { type CollectionBuilder } from "./introspect-db-logic";
+/**
+ * Which `defineCollection` to generate against, for collections written to `outDir`.
+ *
+ * **The detection is the package manifests above the output directory**, unioned from
+ * `outDir` up to and including the project root — the first ancestor holding a
+ * `rebase.json`, or `MAX_LEVELS` up if there is none.
+ *
+ * That is the rule Node itself applies: a file in `config/collections` resolves a bare
+ * specifier through `config/node_modules`, then `<project>/node_modules`, and so on up.
+ * Reading the manifests along that same path answers the only question that matters —
+ * *will this import resolve in the project I am writing into* — from the state on disk
+ * at the moment of generation. The alternatives are all proxies for it: `rebase.json`'s
+ * `apps` block says a CMS scaffold declared an admin app, and a `frontend/` directory
+ * says one was scaffolded, but neither is what the compiler consults, and either can be
+ * true of a project whose `config` package does not depend on `@rebasepro/admin-types`.
+ *
+ * Ambiguity resolves towards the admin panel: a project that declares both packages has
+ * a panel, and `@rebasepro/admin-types` is the flavour that keeps the `admin` block.
+ */
+export declare function detectCollectionBuilder(outDir: string): CollectionBuilder;