@rvoh/dream 2.24.0 → 2.25.0

package/dist/cjs/src/errors/NoColumnsToAlterMigration.js

@@ -1,17 +1,49 @@
 export default class NoColumnsToAlterMigration extends Error {
     table;
     alterDirection;
-    constructor(table, alterDirection) {
+    migrationName;
+    marker;
+    /**
+     * @param table - the table the migration resolved to
+     * @param alterDirection - 'add' for a `-to-` migration, 'remove' for a `-from-` migration
+     * @param migrationName - the migration name the user typed, when available. Only
+     * the standalone `g:migration` flow knows it, so the message degrades to a
+     * table-only explanation when it is omitted.
+     * @param marker - the `-to-`/`-from-` marker that matched within `migrationName`
+     */
+    constructor(table, alterDirection, migrationName, marker) {
         super();
         this.table = table;
         this.alterDirection = alterDirection;
+        this.migrationName = migrationName;
+        this.marker = marker;
     }
     get message() {
-        return `
-no valid columns to ${this.alterDirection === 'remove' ? 'drop from' : 'add to'} table '${this.table}' in this alter migration.
+        const verb = this.alterDirection === 'remove' ? 'drop from' : 'add to';
+        if (!this.migrationName || !this.marker) {
+            return `
+no valid columns to ${verb} table '${this.table}' in this alter migration.
 
 Pass at least one column declaration with a resolvable type, e.g.:
   name:string
+    `;
+        }
+        return `
+no valid columns to ${verb} table '${this.table}' in this alter migration.
+
+The migration name '${this.migrationName}' contains '${this.marker}', which selected that
+table and the '${this.alterDirection}' direction: everything after the marker's first
+occurrence - wherever in the name that falls - is snake-cased and pluralized
+into the table name. A '-to-' anywhere in the name wins, even when a '-from-'
+appears earlier; '-from-' applies only when the name contains no '-to-' at all.
+
+Either:
+
+  - pass at least one column declaration with a resolvable type, e.g.:
+      name:string
+
+  - or, if this was meant to be a hand-written migration, rename it so that
+    neither '-to-' nor '-from-' appears anywhere in the name.
     `;
     }
 }

package/dist/cjs/src/helpers/cli/generateMigration.js

@@ -1,5 +1,6 @@
 import * as path from 'node:path';
 import pluralize from 'pluralize-esm';
+import InvalidMigrationTableName from '../../errors/InvalidMigrationTableName.js';
 import generateMigrationContent, { MIGRATION_TABLE_NAME_PLACEHOLDER, } from '../cli/generateMigrationContent.js';
 import primaryKeyType from '../db/primaryKeyType.js';
 import hyphenize from '../hyphenize.js';
@@ -21,6 +22,30 @@ function tableNameFromSuffix(migrationName, marker) {
         return undefined;
     return migrationName.slice(markerIndex + marker.length) || undefined;
 }
+/**
+ * Whatever table name a generated migration ends up with is written verbatim
+ * into a single-quoted string literal in the migration file, which
+ * `db:migrate` later executes. Anything that is not a plain identifier could
+ * therefore close that literal and inject statements, so the generator fails
+ * closed instead of escaping. Every source of that table name is validated:
+ * the text after a `-to-`/`-from-` marker, the `--table-name` option, and the
+ * name derived from a model name.
+ *
+ * The pattern's job is blocking characters that can escape the generated
+ * string literal, not enforcing an SQL identifier convention: Kysely quotes
+ * identifiers, so a leading digit (`alterTable('2fa_tokens')`) is legal and is
+ * allowed here. Non-ASCII names stay rejected.
+ *
+ * This is a pure string check: it never consults the database, since the
+ * derived name legitimately need not be an existing table (e.g.
+ * `add-treehouse-to-place-styles` targets a Postgres enum).
+ */
+const VALID_DERIVED_TABLE_NAME = /^[a-z0-9_]+$/;
+function validTableNameOrThrow(migrationName, table) {
+    if (!VALID_DERIVED_TABLE_NAME.test(table))
+        throw new InvalidMigrationTableName(migrationName, table);
+    return table;
+}
 export default async function generateMigration({ migrationName, columnsWithTypes, connectionName, fullyQualifiedModelName, fullyQualifiedParentName, tableName: explicitTableName, modelClassName, softDelete = false, }) {
     const migrationsBasePath = connectionName === 'default'
         ? path.join(dreamPath('db'), 'migrations')
@@ -30,7 +55,7 @@ export default async function generateMigration({ migrationName, columnsWithType
     let content = '';
     if (isSTI) {
         content = generateStiMigrationContent({
-            table: snakeify(pluralize(pascalizePath(fullyQualifiedParentName))),
+            table: validTableNameOrThrow(migrationName, snakeify(pluralize(pascalizePath(fullyQualifiedParentName)))),
             columnsWithTypes,
             primaryKeyType: primaryKeyType(connectionName),
             stiChildClassName: modelClassName || pascalizePath(fullyQualifiedModelName),
@@ -38,7 +63,7 @@ export default async function generateMigration({ migrationName, columnsWithType
     }
     else if (fullyQualifiedModelName) {
         content = generateMigrationContent({
-            table: explicitTableName || snakeify(pluralize(pascalizePath(fullyQualifiedModelName))),
+            table: validTableNameOrThrow(migrationName, explicitTableName || snakeify(pluralize(pascalizePath(fullyQualifiedModelName)))),
             columnsWithTypes,
             primaryKeyType: primaryKeyType(connectionName),
             softDelete,
@@ -50,12 +75,17 @@ export default async function generateMigration({ migrationName, columnsWithType
             ? undefined
             : tableNameFromSuffix(migrationName, '-from-');
         const tableName = toTableName || fromTableName;
+        const table = tableName
+            ? validTableNameOrThrow(migrationName, pluralize(snakeify(tableName)))
+            : MIGRATION_TABLE_NAME_PLACEHOLDER;
         content = generateMigrationContent({
-            table: tableName ? pluralize(snakeify(tableName)) : MIGRATION_TABLE_NAME_PLACEHOLDER,
+            table,
             columnsWithTypes,
             primaryKeyType: primaryKeyType(connectionName),
             createOrAlter: 'alter',
             alterDirection: fromTableName ? 'remove' : 'add',
+            migrationName,
+            alterMarker: toTableName ? '-to-' : fromTableName ? '-from-' : undefined,
         });
     }
     await writeGeneratedFile({

package/dist/cjs/src/helpers/cli/generateMigrationContent.js

@@ -10,7 +10,7 @@ import globalClassNameFromFullyQualifiedModelName from '../globalClassNameFromFu
 import snakeify from '../snakeify.js';
 import standardizeFullyQualifiedModelName from '../standardizeFullyQualifiedModelName.js';
 // Sentinel table name used by generateMigration.ts when a standalone
-// migration name matches neither a `-to-<table>` nor `-from-<table>` suffix.
+// migration name contains neither a `-to-<table>` nor `-from-<table>` marker.
 // That path intentionally produces a stub the user is expected to hand-edit
 // (e.g. an index-only migration with no column operations at all), so it's
 // exempt from the "no valid columns" check below.
@@ -23,7 +23,7 @@ const STI_TYPE_COLUMN_NAME = 'type';
 // default. See spec/unit/cli/generateMigrationContent.spec.ts
 // ("deleted_at is deliberately NOT indexed") and the CHANGELOG.
 const COLUMNS_TO_INDEX = [STI_TYPE_COLUMN_NAME];
-export default function generateMigrationContent({ connectionName = 'default', table, columnsWithTypes = [], primaryKeyType = 'bigserial', createOrAlter = 'create', alterDirection = 'add', stiChildClassName, softDelete = false, } = {}) {
+export default function generateMigrationContent({ connectionName = 'default', table, columnsWithTypes = [], primaryKeyType = 'bigserial', createOrAlter = 'create', alterDirection = 'add', migrationName, alterMarker, stiChildClassName, softDelete = false, } = {}) {
     const altering = createOrAlter === 'alter';
     const removingInUp = altering && alterDirection === 'remove';
     let requireCitextExtension = false;
@@ -205,7 +205,7 @@ export async function down(db: Kysely<any>): Promise<void> {
         columnDefs.length === 0 &&
         table !== MIGRATION_TABLE_NAME_PLACEHOLDER &&
         !stiChildClassName) {
-        throw new NoColumnsToAlterMigration(table, alterDirection);
+        throw new NoColumnsToAlterMigration(table, alterDirection, migrationName, alterMarker);
     }
     const citextExtension = requireCitextExtension
         ? `  await DreamMigrationHelpers.createExtension(db, 'citext')\n\n`

package/dist/esm/src/cli/index.js

@@ -105,6 +105,31 @@ ${INDENT}
 ${INDENT}        rename the FK column with Model@alias (snake_case alias becomes the column name):
 ${INDENT}          InternalUser@canceled_by:belongs_to:optional       # canceled_by_id column with index
 ${INDENT}          Messaging/Template@template:belongs_to             # template_id column (strips the namespace from the column name)`);
+/**
+ * The `<migrationName>` argument description for `g:migration`. Exported so
+ * that spec/unit/helpers/cli/generateMigration.spec.ts can read the example
+ * migration names out of this text and run them through the generator: a help
+ * example that drifts from what the generator actually produces then fails the
+ * suite instead of shipping.
+ */
+export const migrationNameArgumentDescription = `Kebab-case name describing the change. A -to-<table_name>
+${INDENT}anywhere in the name — not just at the end — auto-generates
+${INDENT}an add-columns alterTable scaffold for that table;
+${INDENT}-from-<table_name> generates a remove-columns scaffold, but
+${INDENT}only when the name contains no -to- at all. The text after
+${INDENT}the marker's first occurrence is snake-cased and pluralized
+${INDENT}into the table name, so add-a-to-b-to-cs targets b_to_cs. A
+${INDENT}hand-written migration must avoid both strings anywhere in
+${INDENT}its name.
+${INDENT}
+${INDENT}Examples:
+${INDENT}  add-phone-to-users phone:encrypted      # scaffolds alterTable('users', ...)
+${INDENT}  remove-status-from-posts status:string  # scaffolds alterTable('posts', ...)
+${INDENT}  create-many-to-many-posts-users         # WRONG: selects 'many_posts_users'
+${INDENT}    # -to- inside "many-to-many" matches: with no columns
+${INDENT}    # this errors; with columns it silently scaffolds it
+${INDENT}  create-posts-users-join-table           # correct: no marker match
+${INDENT}    # scaffolds alterTable('<table-name>') to hand-edit`;
 export default class DreamCLI {
     /**
      * Starts the Dream console
@@ -151,22 +176,17 @@ export default class DreamCLI {
             .description(`Generates a new Kysely migration file for schema changes. Use this for altering existing tables (adding/removing columns, indexes, constraints). Prefer g:resource or g:model when creating a new model, since they generate the migration along with the model, serializer, and spec files.
 ${INDENT}
 ${INDENT}Examples:
-${INDENT}  # Add columns to an existing table (suffix with -to-<table_name> for auto alterTable scaffolding)
+${INDENT}  # Add columns to an existing table (include -to-<table_name> for auto alterTable scaffolding)
 ${INDENT}  pnpm psy g:migration add-timezone-to-users timezone:string
 ${INDENT}  pnpm psy g:migration add-bio-to-users bio:text:optional avatar_url:string:optional
 ${INDENT}
-${INDENT}  # Remove columns (suffix with -from-<table_name>; columns are described with
+${INDENT}  # Remove columns (include -from-<table_name>; columns are described with
 ${INDENT}  # their types, same shorthand as -to-, so the rollback (down) can recreate them)
 ${INDENT}  pnpm psy g:migration remove-legacy-fields-from-posts legacy_status:string
 ${INDENT}
-${INDENT}  # General schema change (no table suffix — generates empty up/down methods)
+${INDENT}  # General schema change (no -to-/-from- marker — scaffolds alterTable('<table-name>') to hand-edit)
 ${INDENT}  pnpm psy g:migration create-unique-index-on-invitations`)
-            .argument('<migrationName>', `Kebab-case name describing the change. End with -to-<table_name> or -from-<table_name> to auto-generate an alterTable scaffold for that table.
-${INDENT}
-${INDENT}Examples:
-${INDENT}  add-phone-to-users phone:encrypted           # scaffolds alterTable('users', ...)
-${INDENT}  remove-status-from-posts status:string      # scaffolds alterTable('posts', ...)
-${INDENT}  create-join-table-host-places  # empty migration (no table suffix match)`)
+            .argument('<migrationName>', migrationNameArgumentDescription)
             .option('--connection-name <connectionName>', 'the database connection to use for this migration. Only needed for multi-database setups; defaults to "default"')
             .argument('[columnsWithTypes...]', columnsWithTypesDescriptionForMigration)
             .action(async (migrationName, columnsWithTypes, options) => {