@rvoh/dream 2.24.0 → 2.24.1

package/dist/cjs/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) => {

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

@@ -0,0 +1,30 @@
+export default class InvalidMigrationTableName extends Error {
+    migrationName;
+    table;
+    /**
+     * @param migrationName - the migration name the generator was invoked with
+     * @param table - the table name the generator resolved for it
+     */
+    constructor(migrationName, table) {
+        super();
+        this.migrationName = migrationName;
+        this.table = table;
+    }
+    get message() {
+        return `
+generating the migration '${this.migrationName}' resolved the table name:
+  ${this.table}
+
+which is not a valid table name. The table name is written into the generated
+migration, which 'db:migrate' later executes, so it must be a plain
+identifier: lowercase letters, digits and underscores only.
+
+A standalone 'g:migration' takes the table from the text after the first
+'-to-'/'-from-' in the name, snake-cased and pluralized, e.g.:
+  add-phone-to-users
+
+A model generator takes it from the model name, or verbatim from
+'--table-name'.
+    `;
+    }
+}

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) => {

package/dist/esm/src/errors/InvalidMigrationTableName.js

@@ -0,0 +1,30 @@
+export default class InvalidMigrationTableName extends Error {
+    migrationName;
+    table;
+    /**
+     * @param migrationName - the migration name the generator was invoked with
+     * @param table - the table name the generator resolved for it
+     */
+    constructor(migrationName, table) {
+        super();
+        this.migrationName = migrationName;
+        this.table = table;
+    }
+    get message() {
+        return `
+generating the migration '${this.migrationName}' resolved the table name:
+  ${this.table}
+
+which is not a valid table name. The table name is written into the generated
+migration, which 'db:migrate' later executes, so it must be a plain
+identifier: lowercase letters, digits and underscores only.
+
+A standalone 'g:migration' takes the table from the text after the first
+'-to-'/'-from-' in the name, snake-cased and pluralized, e.g.:
+  add-phone-to-users
+
+A model generator takes it from the model name, or verbatim from
+'--table-name'.
+    `;
+    }
+}

package/dist/esm/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/esm/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/esm/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/types/src/cli/index.d.ts

@@ -16,6 +16,14 @@ export type SpawnOptions = Omit<NodeSpawnOptions, 'shell'> & {
 export declare const CLI_INDENT = "                  ";
 export declare const baseColumnsWithTypesDescription = "space separated snake-case properties like this:\n                      title:citext subtitle:string body_markdown:text style:enum:post_styles:formal,informal\n                  \n                  all properties default to not nullable; null can be allowed by appending ':optional':\n                      subtitle:string:optional\n                  \n                  supported types:\n                      - uuid:\n                      - uuid[]:\n                          a column optimized for storing UUIDs\n                  \n                      - citext:\n                      - citext[]:\n                          case insensitive text (indexes and queries are automatically case insensitive)\n                  \n                      - encrypted:\n                          encrypted text (used in conjunction with the @deco.Encrypted decorator)\n                  \n                      - string:\n                      - string[]:\n                          varchar; allowed length defaults to 255, but may be customized, e.g.: subtitle:string:128 or subtitle:string:128:optional\n                  \n                      - text\n                      - text[]\n                      - date\n                      - date[]\n                      - datetime\n                      - datetime[]\n                      - time\n                      - time[]\n                      - timetz\n                      - timetz[]\n                      - integer\n                      - integer[]\n                      - boolean\n                      - boolean[]\n                  \n                      - decimal:\n                      - decimal[]:\n                          precision,scale is required, e.g.: volume:decimal:3,2 or volume:decimal:3,2:optional\n                  \n                          leveraging arrays, add the \"[]\" suffix, e.g.: volume:decimal[]:3,2\n                  \n                      - enum:\n                      - enum[]:\n                          include the enum name to automatically create the enum:\n                            type:enum:room_types:bathroom,kitchen,bedroom or type:enum:room_types:bathroom,kitchen,bedroom:optional\n                  \n                          omit the enum values to leverage an existing enum (omits the enum type creation):\n                            type:enum:room_types or type:enum:room_types:optional\n                  \n                          leveraging arrays, add the \"[]\" suffix, e.g.: type:enum[]:room_types:bathroom,kitchen,bedroom";
 export declare const columnsWithTypesDescriptionForStiChild: string;
+/**
+ * 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 declare const migrationNameArgumentDescription = "Kebab-case name describing the change. A -to-<table_name>\n                  anywhere in the name \u2014 not just at the end \u2014 auto-generates\n                  an add-columns alterTable scaffold for that table;\n                  -from-<table_name> generates a remove-columns scaffold, but\n                  only when the name contains no -to- at all. The text after\n                  the marker's first occurrence is snake-cased and pluralized\n                  into the table name, so add-a-to-b-to-cs targets b_to_cs. A\n                  hand-written migration must avoid both strings anywhere in\n                  its name.\n                  \n                  Examples:\n                    add-phone-to-users phone:encrypted      # scaffolds alterTable('users', ...)\n                    remove-status-from-posts status:string  # scaffolds alterTable('posts', ...)\n                    create-many-to-many-posts-users         # WRONG: selects 'many_posts_users'\n                      # -to- inside \"many-to-many\" matches: with no columns\n                      # this errors; with columns it silently scaffolds it\n                    create-posts-users-join-table           # correct: no marker match\n                      # scaffolds alterTable('<table-name>') to hand-edit";
 export default class DreamCLI {
     /**
      * Starts the Dream console

package/dist/types/src/errors/InvalidMigrationTableName.d.ts

@@ -0,0 +1,10 @@
+export default class InvalidMigrationTableName extends Error {
+    migrationName: string;
+    table: string;
+    /**
+     * @param migrationName - the migration name the generator was invoked with
+     * @param table - the table name the generator resolved for it
+     */
+    constructor(migrationName: string, table: string);
+    get message(): string;
+}

package/dist/types/src/errors/NoColumnsToAlterMigration.d.ts

@@ -1,6 +1,16 @@
 export default class NoColumnsToAlterMigration extends Error {
     table: string;
     alterDirection: 'add' | 'remove';
-    constructor(table: string, alterDirection: 'add' | 'remove');
+    migrationName: string | undefined;
+    marker: '-to-' | '-from-' | undefined;
+    /**
+     * @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: string, alterDirection: 'add' | 'remove', migrationName?: string, marker?: '-to-' | '-from-');
     get message(): string;
 }

package/dist/types/src/helpers/cli/generateMigrationContent.d.ts

@@ -1,6 +1,6 @@
 import { LegacyCompatiblePrimaryKeyType } from '../../types/db.js';
 export declare const MIGRATION_TABLE_NAME_PLACEHOLDER = "<table-name>";
-export default function generateMigrationContent({ connectionName, table, columnsWithTypes, primaryKeyType, createOrAlter, alterDirection, stiChildClassName, softDelete, }?: {
+export default function generateMigrationContent({ connectionName, table, columnsWithTypes, primaryKeyType, createOrAlter, alterDirection, migrationName, alterMarker, stiChildClassName, softDelete, }?: {
     connectionName?: string;
     table?: string | undefined;
     columnsWithTypes?: string[] | undefined;
@@ -8,13 +8,27 @@ export default function generateMigrationContent({ connectionName, table, column
     createOrAlter?: 'create' | 'alter' | undefined;
     /**
      * Only meaningful when `createOrAlter: 'alter'`. `'add'` (the default,
-     * matching a `-to-<table>`-suffixed migration name) emits column additions
-     * in `up` and the matching drops in `down`. `'remove'` (matching a
-     * `-from-<table>`-suffixed migration name) inverts this: `up` drops the
+     * matching a migration name containing a `-to-<table>` marker) emits column
+     * additions in `up` and the matching drops in `down`. `'remove'` (matching a
+     * migration name containing a `-from-<table>` marker) inverts this: `up` drops the
      * named columns and `down` re-adds them with their declared types, so
      * `down` is the rollback that restores what `up` removed.
      */
     alterDirection?: 'add' | 'remove' | undefined;
+    /**
+     * The migration name the user typed. Only the standalone `g:migration` flow
+     * has one; it is threaded through solely so `NoColumnsToAlterMigration` can
+     * name it, and the error message degrades to a table-only explanation when it
+     * (or `alterMarker`) is absent.
+     */
+    migrationName?: string | undefined;
+    /**
+     * The `-to-`/`-from-` marker that matched within `migrationName` and resolved
+     * both the table and the add/remove direction (alter mode itself is
+     * unconditional on that path). Reported by `NoColumnsToAlterMigration`; see
+     * `migrationName`.
+     */
+    alterMarker?: '-to-' | '-from-' | undefined;
     stiChildClassName?: string | undefined;
     /**
      * When true (and creating a new table), auto-emits a nullable `deleted_at`