@rebasepro/server-postgres 0.13.0 → 0.13.1-canary.g1822133

package/src/schema/introspect-db-logic.ts

@@ -6,6 +6,7 @@
  * no process.exit.  It is imported by introspect-db.ts (the CLI entry-point)
  * and consumed directly by tests.
  */
+import { firstFreeKey, toWireKey } from "@rebasepro/utils";
 import { inferPropertyFromData } from "./introspect-db-inference";
 import { humanize } from "./introspect-db-naming";
 import { mapPgType } from "./introspect-db-types";
@@ -218,7 +219,14 @@ export function singularize(word: string): string {
  * e.g. "company_token" -> "companyTokenCollection"
  */
 export function toCollectionVarName(tableName: string): string {
-    return tableName.replace(/_([a-z])/g, (_g, letter: string) => letter.toUpperCase()) + "Collection";
+    const camel = tableName.replace(/_([a-z])/g, (_g, letter: string) => letter.toUpperCase()) + "Collection";
+    // Only reshapes names that are not identifiers already, so every table that
+    // generated a working file keeps the exact variable name it had. A table
+    // called `2024 archive` used to emit `const 2024 archiveCollection`, which
+    // is three syntax errors rather than a declaration.
+    if (JS_IDENTIFIER.test(camel)) return camel;
+    const sanitized = camel.replace(/[^A-Za-z0-9_$]/g, "_");
+    return /^[0-9]/.test(sanitized) ? `_${sanitized}` : sanitized;
 }
 
 export function getIconForTable(tableName: string): string {
@@ -572,10 +580,61 @@ 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 const ADMIN_TYPES_PACKAGE = "@rebasepro/admin-types";
+export const COMMON_PACKAGE = "@rebasepro/common";
+export 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;
 }
 
 /** Adds entries to a property's `validation` block, creating it if absent. */
@@ -601,8 +660,17 @@ function hasGeneratedKey(extra: string, key: string): boolean {
     return new RegExp(`(^|[\\s{,])${key}\\s*:`).test(extra);
 }
 
-/** Adds entries to a property's `admin` block, creating it if absent. */
-function withAdminOptions(extra: string, entries: string[]): string {
+/**
+ * Adds entries to a property's `admin` block, creating it if absent.
+ *
+ * `emitAdmin` is false for the headless flavours, where `BaseProperty` has no
+ * `admin` field to put them in — see {@link CollectionBuilder}. The options are
+ * dropped rather than relocated: every one of them (`readOnly`, `multiline`,
+ * `hideFromCollection`, `urlPreview`) describes a form widget, and there is no
+ * form.
+ */
+function withAdminOptions(extra: string, entries: string[], emitAdmin = true): string {
+    if (!emitAdmin) return extra;
     if (entries.length === 0) return extra;
     const block = entries.map((e) => `                ${e}`).join(",\n");
     if (extra.includes("admin: {")) {
@@ -616,22 +684,35 @@ function quote(value: string): string {
     return JSON.stringify(value);
 }
 
+const JS_IDENTIFIER = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+
 /**
- * The first candidate key not already used, or a numbered fallback.
+ * An object key for the generated file: verbatim when the name is a JavaScript
+ * identifier, quoted otherwise.
+ *
+ * Postgres constrains an identifier only by quoting, so `order`, `full name`
+ * and `2fa_enabled` are all ordinary column names — and all three produced a
+ * file that did not parse when written as a bare key.
  *
- * The numbered tail exists so this is total: a table can hold two foreign keys
- * whose columns strip to the same name, and a function that returns a key it
- * cannot guarantee is free has just moved the duplicate one line down.
+ * Still needed now that keys are camel-cased rather than copied from the
+ * column: `toWireKey` splits on separators and joins, which fixes `full name`
+ * but cannot fix a name that is not an identifier for some other reason —
+ * `2fa_enabled` becomes `2faEnabled`, still leading with a digit, and `order`
+ * was never a separator problem at all.
  */
-function firstFreeKey(candidates: string[], taken: ReadonlyMap<string, unknown>): string {
-    for (const candidate of candidates) {
-        if (!taken.has(candidate)) return candidate;
-    }
-    const base = candidates[candidates.length - 1];
-    for (let suffix = 2; ; suffix++) {
-        const candidate = `${base}_${suffix}`;
-        if (!taken.has(candidate)) return candidate;
-    }
+function propKey(name: string): string {
+    return JS_IDENTIFIER.test(name) ? name : quote(name);
+}
+
+/**
+ * Text safe to put after `//`.
+ *
+ * A table comment or a classification reason is free text out of the database.
+ * A newline in one ended the comment and let the rest of the value continue as
+ * code.
+ */
+function commentText(value: string): string {
+    return value.replace(/\s*[\r\n]+\s*/g, " ");
 }
 
 /** A property-key array, one key per line, indented for the admin block. */
@@ -674,7 +755,16 @@ export function generateCollectionFile(
             .map((u) => u.column_names[0])
     );
 
-    const imports = new Set<string>(['import { PostgresCollectionConfig } from "@rebasepro/types";']);
+    const builder: CollectionBuilder = context.builder ?? "admin-types";
+    /** Whether the target project has an `admin` field to write into at all. */
+    const emitAdmin = builder === "admin-types";
+
+    const BUILDER_IMPORT: Record<CollectionBuilder, string> = {
+        "admin-types": `import { defineCollection } from ${quote(ADMIN_TYPES_PACKAGE)};`,
+        common: `import { defineCollection } from ${quote(COMMON_PACKAGE)};`,
+        annotation: `import { PostgresCollectionConfig } from ${quote(TYPES_PACKAGE)};`
+    };
+    const imports = new Set<string>([BUILDER_IMPORT[builder]]);
 
     /**
      * Imports the collection a relation points at — unless it is this one.
@@ -688,14 +778,48 @@ export function generateCollectionFile(
      */
     const importCollection = (otherTable: string): string => {
         const varName = toCollectionVarName(otherTable);
-        if (otherTable !== tableName) imports.add(`import ${varName} from "./${otherTable}";`);
+        if (otherTable !== tableName) imports.add(`import ${varName} from ${quote(`./${otherTable}`)};`);
         return varName;
     };
 
+    /**
+     * A relation's `target` thunk, with its return type spelled out.
+     *
+     * The annotation is what makes `defineCollection` survive a relational schema.
+     * Without an explicit type on the const, the collection's type is *inferred*,
+     * and a relation cycle — `posts` belongs to `authors`, `authors` has many
+     * `posts`; or `employees.reports_to -> employees`, which northwind, chinook and
+     * musicbrainz all have — makes that inference circular: `TS7022: implicitly has
+     * type 'any' because it is referenced directly or indirectly in its own
+     * initializer`, plus `TS7023` on the thunk and `TS2303` on the import alias.
+     * Naming the return type lets the checker type the thunk without resolving the
+     * collection it points at, which breaks the cycle. Nothing else is given up:
+     * the inference that matters runs over `properties`, not over `relations`.
+     *
+     * The annotated flavour has no cycle to break — its const is already typed — so
+     * it keeps the plainer thunk it has always emitted.
+     */
+    const relationTarget = (targetVarName: string): string => {
+        if (builder === "annotation") return `() => ${targetVarName}`;
+        imports.add(`import type { AnyCollectionConfig } from ${quote(TYPES_PACKAGE)};`);
+        return `(): AnyCollectionConfig => ${targetVarName}`;
+    };
+
     let propsOutput = "";
     let relationsOutput = "";
     const orderEntries: PropertyOrderEntry[] = [];
     const propertyBlocks = new Map<string, string>();
+    /**
+     * Column → the property key it was generated under.
+     *
+     * Needed because the structural helpers below (`deriveTitleProperty`,
+     * `deriveKanbanProperty`, `deriveSort`) answer in *columns* — they read
+     * `pg_attribute` — while `display.title`, `kanban.columnProperty` and
+     * `sort` name **properties**. The two used to be the same string, so
+     * nothing carried the translation; now `full_name` is generated as
+     * `fullName` and a title pointing at `full_name` points at nothing.
+     */
+    const keyByColumn = new Map<string, string>();
     /** Properties the list view will not render, so `listProperties` skips them. */
     const hiddenFromCollection = new Set<string>();
     let columnIndex = 0;
@@ -711,6 +835,23 @@ export function generateCollectionFile(
 
         const currentIndex = columnIndex++;
 
+        // The key this column is generated under — its *wire* name, which is
+        // not its column name. `columnName` below carries the column, so the
+        // two never have to agree and the API stops carrying `user_id` next to
+        // `displayName`.
+        //
+        // Camel-casing makes collisions possible where none existed: `user_id`
+        // and `userId` are two columns and one key, which is a duplicate key in
+        // an object literal — a TypeScript error that stops the whole generated
+        // collection compiling. Resolved the same way the foreign-key loop
+        // below resolves its own: first free candidate, then a numbered tail,
+        // so no column is ever dropped. The raw column name is the second
+        // candidate, so the loser of a collision still gets a name that means
+        // something. Deterministic for a given database: the columns arrive in
+        // ordinal order, so the same schema always yields the same keys.
+        const propertyKey = firstFreeKey([toWireKey(col.column_name), col.column_name], propertyBlocks);
+        keyByColumn.set(col.column_name, propertyKey);
+
         // Check if this column uses a PostgreSQL enum type
         const colEnumValues = enumMap.get(col.udt_name);
         const isEnumColumn = col.data_type === "USER-DEFINED" && colEnumValues !== undefined;
@@ -727,7 +868,7 @@ export function generateCollectionFile(
 
         if (!isEnumColumn && sampleData && sampleData.length > 0) {
             const values = sampleData.map(r => r[col.column_name]);
-            const inferred = inferPropertyFromData(col.column_name, col.data_type, propType, values, meta.pks.includes(col.column_name));
+            const inferred = inferPropertyFromData(col.column_name, col.data_type, propType, values, meta.pks.includes(col.column_name), emitAdmin);
             if (inferred.propType) finalPropType = inferred.propType;
             if (inferred.extra) inferenceExtra = inferred.extra;
         }
@@ -737,7 +878,7 @@ export function generateCollectionFile(
         // Enum values — generate real enum from the PG enum
         if (isEnumColumn && colEnumValues) {
             const enumEntries = colEnumValues
-                .map((v) => `{ id: "${v}", label: "${humanize(v)}" }`)
+                .map((v) => `{ id: ${quote(v)}, label: ${quote(humanize(v))} }`)
                 .join(", ");
             extra += `\n            enum: [${enumEntries}],`;
         } else if (columnChecks?.enumValues && !inferenceExtra.includes("enum:") && propType === "string") {
@@ -754,13 +895,16 @@ export function generateCollectionFile(
         // Date auto-value heuristics
         if (finalPropType === "date") {
             if (colNameLower === "created_at" || colNameLower === "createdat") {
-                extra += "\n            autoValue: \"on_create\",\n            admin: {\n                readOnly: true,\n                hideFromCollection: true\n            },";
-                hiddenFromCollection.add(col.column_name);
+                extra += "\n            autoValue: \"on_create\",";
+                extra = withAdminOptions(extra, ["readOnly: true", "hideFromCollection: true"], emitAdmin);
+                hiddenFromCollection.add(propertyKey);
             } else if (colNameLower === "updated_at" || colNameLower === "updatedat") {
-                extra += "\n            autoValue: \"on_update\",\n            admin: {\n                readOnly: true,\n                hideFromCollection: true\n            },";
-                hiddenFromCollection.add(col.column_name);
+                extra += "\n            autoValue: \"on_update\",";
+                extra = withAdminOptions(extra, ["readOnly: true", "hideFromCollection: true"], emitAdmin);
+                hiddenFromCollection.add(propertyKey);
             } else if (col.column_default && (col.column_default.includes("now()") || col.column_default.includes("CURRENT_TIMESTAMP"))) {
-                extra += "\n            autoValue: \"on_create\",\n            admin: {\n                readOnly: true\n            },";
+                extra += "\n            autoValue: \"on_create\",";
+                extra = withAdminOptions(extra, ["readOnly: true"], emitAdmin);
             }
         }
 
@@ -776,9 +920,9 @@ export function generateCollectionFile(
                 else if (innerType === "boolean") colType = "boolean[]";
             }
             if (colType) {
-                extra += `\n            columnType: "${colType}",`;
+                extra += `\n            columnType: ${quote(colType)},`;
             }
-            extra += `\n            of: { name: "${humanize(col.column_name)} Item", type: "${innerType}" },`;
+            extra += `\n            of: { name: ${quote(`${humanize(col.column_name)} Item`)}, type: ${quote(innerType)} },`;
         } else if (finalPropType === "map" && !inferenceExtra.includes("keyValue: true") && !inferenceExtra.includes("properties: {")) {
             extra += "\n            keyValue: true,";
         }
@@ -789,20 +933,20 @@ export function generateCollectionFile(
             const isMedia = colNameLower.includes("image") || colNameLower.includes("avatar") || colNameLower.includes("photo") || colNameLower.includes("logo") || colNameLower.includes("cover");
 
             if (isMedia) {
-                extra += `\n            storage: {\n                storagePath: "${tableName}/${col.column_name}"\n            },`;
+                extra += `\n            storage: {\n                storagePath: ${quote(`${tableName}/${col.column_name}`)}\n            },`;
             } else if (isUrl) {
                 extra += "\n            url: true,";
             } else if (colNameLower === "description" || colNameLower === "summary" || colNameLower === "excerpt") {
-                extra += "\n            admin: {\n                multiline: true\n            },";
+                extra = withAdminOptions(extra, ["multiline: true"], emitAdmin);
             } else if (colNameLower === "content" || colNameLower === "body") {
                 // Inside `admin`, because that is where both options live. At the
                 // top of the property — where these were — the generated file
                 // does not compile: `StringProperty` declares neither. Six of
                 // OpenStreetMap's tables have a `body` column, which is how this
                 // surfaced.
-                extra += "\n            admin: {\n                multiline: true,\n                markdown: true\n            },";
+                extra = withAdminOptions(extra, ["multiline: true", "markdown: true"], emitAdmin);
             } else if (col.data_type === "text") {
-                extra += "\n            admin: {\n                multiline: true\n            },";
+                extra = withAdminOptions(extra, ["multiline: true"], emitAdmin);
             }
         }
 
@@ -857,9 +1001,9 @@ export function generateCollectionFile(
             const options = ["readOnly: true"];
             if (isDerivedIndexColumn(col) && !hasGeneratedKey(extra, "hideFromCollection")) {
                 options.push("hideFromCollection: true");
-                hiddenFromCollection.add(col.column_name);
+                hiddenFromCollection.add(propertyKey);
             }
-            extra = withAdminOptions(extra, options);
+            extra = withAdminOptions(extra, options, emitAdmin);
         }
 
         // `COMMENT ON COLUMN` — documentation the author already wrote, which
@@ -872,7 +1016,7 @@ export function generateCollectionFile(
         // Identify IDs (unless already inferred as UUID/CUID by inferenceEngine)
         if (meta.pks.includes(col.column_name)) {
             if (isCompositePk) {
-                extra += `\n            // Part of composite primary key (${meta.pks.join(", ")})`;
+                extra += `\n            // Part of composite primary key (${commentText(meta.pks.join(", "))})`;
             } else if (finalPropType === "number" && !inferenceExtra.includes("isId:")) {
                 extra += "\n            isId: \"increment\",";
             } else if (col.data_type.toLowerCase() === "uuid" && !inferenceExtra.includes("isId:")) {
@@ -901,7 +1045,7 @@ export function generateCollectionFile(
         const humanName = humanize(col.column_name);
 
         orderEntries.push({
-            key: col.column_name,
+            key: propertyKey,
             ctx: {
                 propType: finalPropType,
                 isPk: meta.pks.includes(col.column_name),
@@ -912,11 +1056,11 @@ export function generateCollectionFile(
             }
         });
 
-        propertyBlocks.set(col.column_name, `
-        ${col.column_name}: {
-            name: "${humanName}",
-            columnName: "${col.column_name}",
-            type: "${finalPropType}",${extra}
+        propertyBlocks.set(propertyKey, `
+        ${propKey(propertyKey)}: {
+            name: ${quote(humanName)},
+            columnName: ${quote(col.column_name)},
+            type: ${quote(finalPropType)},${extra}
         },`);
     }
 
@@ -936,11 +1080,17 @@ export function generateCollectionFile(
             // every foreign key after the table it points at — `area_tag (area,
             // tag)` — so 67 of its 339 collections came out with a property
             // declared twice.
+            //
+            // Camel-cased for the same reason the columns above are: this is a
+            // property key, it sits in the same object literal, and a
+            // `blog_author` beside a `publishedAt` is the two-conventions
+            // defect reproduced inside a single collection.
+            const stripped = toWireKey(fk.column_name.replace(/_id$/, ""));
             const relName = firstFreeKey(
                 [
-                    fk.column_name.replace(/_id$/, ""),
-                    targetTableName,
-                    `${fk.column_name.replace(/_id$/, "")}_relation`
+                    stripped,
+                    toWireKey(targetTableName),
+                    `${stripped}Relation`
                 ],
                 propertyBlocks
             );
@@ -962,14 +1112,14 @@ export function generateCollectionFile(
             const relHumanName = humanize(relName);
 
             propertyBlocks.set(relName, `
-        ${relName}: {
-            name: "${relHumanName}",
+        ${propKey(relName)}: {
+            name: ${quote(relHumanName)},
             type: "relation",
-            // mapped from foreign key: ${fk.column_name} -> ${targetTableName}(${fk.foreign_column_name})
+            // mapped from foreign key: ${commentText(fk.column_name)} -> ${commentText(targetTableName)}(${commentText(fk.foreign_column_name)})
             relation: {
                 kind: "belongsTo",
-                target: () => ${targetCollectionCamel},
-                localKey: "${fk.column_name}"
+                target: ${relationTarget(targetCollectionCamel)},
+                localKey: ${quote(fk.column_name)}
             }
         },`);
         }
@@ -986,10 +1136,10 @@ export function generateCollectionFile(
         relationsOutput += `
         {
             kind: "hasMany",
-            relationName: "${sourceTableName}",
-            target: () => ${targetCollectionCamel},
-            // the ${sourceTableName}.${fk.column_name} FK points back here
-            foreignKeyOnTarget: "${fk.column_name}"
+            relationName: ${quote(sourceTableName)},
+            target: ${relationTarget(targetCollectionCamel)},
+            // the ${commentText(sourceTableName)}.${commentText(fk.column_name)} FK points back here
+            foreignKeyOnTarget: ${quote(fk.column_name)}
         },`;
     }
 
@@ -1018,12 +1168,12 @@ export function generateCollectionFile(
             relationsOutput += `
         {
             kind: "manyToMany",
-            relationName: "${relPropName}",
-            target: () => ${tableName}Collection,
+            relationName: ${quote(relPropName)},
+            target: ${relationTarget(toCollectionVarName(tableName))},
             through: {
-                table: "${jt}",
-                sourceColumn: "${thisFk.column_name}",
-                targetColumn: "${otherFk.column_name}"
+                table: ${quote(jt)},
+                sourceColumn: ${quote(thisFk.column_name)},
+                targetColumn: ${quote(otherFk.column_name)}
             }
         },`;
             continue;
@@ -1045,14 +1195,14 @@ export function generateCollectionFile(
             const thisFk = joinFks.find((fk) => fk.foreign_table_name === tableName);
 
             const throughCode = thisFk
-                ? `\n            through: {\n                table: "${jt}",\n                sourceColumn: "${thisFk.column_name}",\n                targetColumn: "${otherFk.column_name}"\n            }`
+                ? `\n            through: {\n                table: ${quote(jt)},\n                sourceColumn: ${quote(thisFk.column_name)},\n                targetColumn: ${quote(otherFk.column_name)}\n            }`
                 : "";
 
             relationsOutput += `
         {
             kind: "manyToMany",
-            relationName: "${targetTableName}",
-            target: () => ${targetCollectionCamel},${throughCode}
+            relationName: ${quote(targetTableName)},
+            target: ${relationTarget(targetCollectionCamel)},${throughCode}
         },`;
         }
     }
@@ -1071,7 +1221,7 @@ export function generateCollectionFile(
     // config, where they have not belonged since the admin block was split out:
     // `PostgresCollectionConfig` does not declare them, so every generated file
     // was a type error, and the panel — which reads the block — never saw them.
-    const adminEntries: string[] = [`icon: "${icon}"`];
+    const adminEntries: string[] = [`icon: ${quote(icon)}`];
 
     if (classification) {
         const derivedFacts = context.metadata
@@ -1088,14 +1238,17 @@ export function generateCollectionFile(
         }
 
         if (derivedFacts) {
+            // Each of these comes back as a column and is emitted as a property.
+            const asProperty = (column: string): string => keyByColumn.get(column) ?? toWireKey(column);
+
             const titleProperty = deriveTitleProperty(derivedFacts);
-            if (titleProperty) adminEntries.push(`titleProperty: ${quote(titleProperty)}`);
+            if (titleProperty) adminEntries.push(`display: { title: ${quote(asProperty(titleProperty))} }`);
 
             const kanbanProperty = deriveKanbanProperty(derivedFacts);
-            if (kanbanProperty) adminEntries.push(`kanban: {\n            columnProperty: ${quote(kanbanProperty)}\n        }`);
+            if (kanbanProperty) adminEntries.push(`kanban: {\n            columnProperty: ${quote(asProperty(kanbanProperty))}\n        }`);
 
             const sort = deriveSort(derivedFacts);
-            if (sort) adminEntries.push(`sort: [${quote(sort[0])}, "desc"]`);
+            if (sort) adminEntries.push(`sort: [${quote(asProperty(sort[0]))}, "desc"]`);
         }
 
         const listProperties = deriveListProperties(sortedPropertiesOrder, hiddenFromCollection);
@@ -1106,7 +1259,14 @@ export function generateCollectionFile(
 
     adminEntries.push(`propertiesOrder: ${formatKeyList(sortedPropertiesOrder)}`);
 
-    const adminBlock = `\n    admin: {\n        ${adminEntries.join(",\n        ")}\n    }`;
+    // Every entry above names a property key, and with `defineCollection` those
+    // keys are now checked against `properties` — a stale `propertiesOrder` entry
+    // left behind by a renamed column is a compile error rather than a silent
+    // no-op. Which is also why the block cannot be emitted where the field is not
+    // declared: see {@link CollectionBuilder}.
+    const adminBlock = emitAdmin
+        ? `\n    admin: {\n        ${adminEntries.join(",\n        ")}\n    }`
+        : "";
 
     const descriptionBlock = tableComment
         ? `\n    description: ${quote(tableComment)},`
@@ -1116,20 +1276,36 @@ export function generateCollectionFile(
     // decision the reader may disagree with. Naming the evidence tells them
     // which line to delete when they do.
     const classificationNote = classification && classification.role !== "entity"
-        ? `\n// Introspected as a ${classification.role}: ${classification.reason}.\n`
+        ? `\n// Introspected as a ${commentText(classification.role)}: ${commentText(classification.reason)}.\n`
         : "";
 
     const collectionVarName = toCollectionVarName(tableName);
-    const fileContent = `${Array.from(imports).join("\n")}
+    // `const x = defineCollection({ … })` is also the shape the ts-morph schema
+    // editor in `@rebasepro/server` expects — `COLLECTION_FACTORIES` — so an
+    // introspected collection is now editable from the panel the way a scaffolded
+    // one is.
+    const [open, close] = builder === "annotation"
+        ? [`const ${collectionVarName}: PostgresCollectionConfig = {`, "};"]
+        : [`const ${collectionVarName} = defineCollection({`, "});"];
+    // Package imports first, then siblings. `AnyCollectionConfig` is added the
+    // moment the first relation needs it — which is after the sibling collections
+    // it points at have already been added — and only when a relation needs it, so
+    // a project with `noUnusedLocals` never sees an import it does not use.
+    const importLines = Array.from(imports);
+    const orderedImports = [
+        ...importLines.filter((line) => !line.includes('from "./')),
+        ...importLines.filter((line) => line.includes('from "./'))
+    ];
+    const fileContent = `${orderedImports.join("\n")}
 ${classificationNote}
-const ${collectionVarName}: PostgresCollectionConfig = {
-    name: "${collectionName}",
-    singularName: "${singular}",
-    slug: "${tableName}",
-    table: "${tableName}",${descriptionBlock}
+${open}
+    name: ${quote(collectionName)},
+    singularName: ${quote(singular)},
+    slug: ${quote(tableName)},
+    table: ${quote(tableName)},${descriptionBlock}
     properties: {${propsOutput}
     },${relationsBlock}${adminBlock}
-};
+${close}
 
 export default ${collectionVarName};
 `;
@@ -1146,7 +1322,7 @@ export function generateIndexContent(fileNames: string[]): string {
     let arrayElements = "";
     for (const f of sorted) {
         const varName = toCollectionVarName(f);
-        imports += `import ${varName} from "./${f}";\n`;
+        imports += `import ${varName} from ${quote(`./${f}`)};\n`;
         arrayElements += `    ${varName},\n`;
     }
     return `${imports}\nexport const collections = [\n${arrayElements}];\n`;
@@ -1168,7 +1344,7 @@ export function mergeIndexContent(existingContent: string, newFileNames: string[
     for (const f of sorted) {
         if (!existingImports.has(f)) {
             const varName = toCollectionVarName(f);
-            newImports += `import ${varName} from "./${f}";\n`;
+            newImports += `import ${varName} from ${quote(`./${f}`)};\n`;
             newElements += `    ${varName},\n`;
         }
     }

package/src/schema/introspect-db-project.ts

@@ -0,0 +1,78 @@
+/**
+ * What the project being introspected into can actually import.
+ *
+ * The generator is pure — `introspect-db-logic.ts` reads no files — so the one
+ * question it cannot answer for itself lives here: which `defineCollection`, if
+ * any, will resolve from the directory the collections are written to.
+ */
+import fs from "fs";
+import path from "path";
+
+import { ADMIN_TYPES_PACKAGE, COMMON_PACKAGE, type CollectionBuilder } from "./introspect-db-logic";
+
+/** How far up to look before giving up, if no project root announces itself. */
+const MAX_LEVELS = 8;
+
+/** Every dependency name a manifest declares, in any of the three fields. */
+function declaredDependencies(manifestPath: string): Set<string> {
+    const names = new Set<string>();
+    let parsed: unknown;
+    try {
+        parsed = JSON.parse(fs.readFileSync(manifestPath, "utf-8"));
+    } catch {
+        // A malformed or unreadable package.json is not this function's problem
+        // to report — it answers "can this import resolve", and the answer is no.
+        return names;
+    }
+    if (typeof parsed !== "object" || parsed === null) return names;
+    const manifest = parsed as Record<string, unknown>;
+    for (const field of ["dependencies", "devDependencies", "peerDependencies"]) {
+        const block = manifest[field];
+        if (typeof block === "object" && block !== null) {
+            for (const name of Object.keys(block)) names.add(name);
+        }
+    }
+    return names;
+}
+
+/**
+ * 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 function detectCollectionBuilder(outDir: string): CollectionBuilder {
+    let dir = path.resolve(outDir);
+    const declared = new Set<string>();
+
+    for (let level = 0; level < MAX_LEVELS; level++) {
+        const manifest = path.join(dir, "package.json");
+        if (fs.existsSync(manifest)) {
+            for (const name of declaredDependencies(manifest)) declared.add(name);
+        }
+        // The project root, and the last level worth reading: anything above it
+        // belongs to whatever the project happens to be checked out inside.
+        if (fs.existsSync(path.join(dir, "rebase.json"))) break;
+
+        const parent = path.dirname(dir);
+        if (parent === dir) break;
+        dir = parent;
+    }
+
+    if (declared.has(ADMIN_TYPES_PACKAGE)) return "admin-types";
+    if (declared.has(COMMON_PACKAGE)) return "common";
+    return "annotation";
+}