@rvoh/dream 2.25.0 → 2.26.0

package/dist/cjs/src/errors/serializers/NonDreamSerializerDerivedFromGlobalSerializerForSpecifiedKey.js

@@ -1,15 +1,18 @@
 import { inspect } from 'node:util';
+import serializerResolutionContextMessage from './serializerResolutionContextMessage.js';
 export default class NonDreamSerializerDerivedFromGlobalSerializerForSpecifiedKey extends Error {
     viewModel;
     serializerKey;
     globalName;
     serializer;
-    constructor(viewModel, serializerKey, globalName, serializer) {
+    resolutionContext;
+    constructor(viewModel, serializerKey, globalName, serializer, resolutionContext) {
         super();
         this.viewModel = viewModel;
         this.serializerKey = serializerKey;
         this.globalName = globalName;
         this.serializer = serializer;
+        this.resolutionContext = resolutionContext;
     }
     get message() {
         const className = this.viewModel?.sanitizedConstructorName ?? this.viewModel.constructor.name;
@@ -17,7 +20,6 @@ export default class NonDreamSerializerDerivedFromGlobalSerializerForSpecifiedKe
 ${className} specified a global name of "${this.globalName}" for serializer key "${this.serializerKey}",
 but the derived serializer is not a Dream serializer:
 
-${inspect(this.serializer)}
-`;
+${inspect(this.serializer)}${serializerResolutionContextMessage(this.serializerKey, this.resolutionContext)}`;
     }
 }

package/dist/cjs/src/errors/serializers/serializerResolutionContextMessage.js

@@ -0,0 +1,46 @@
+/**
+ * @internal
+ *
+ * Renders the trailing "how did resolution reach this class" block shared by the five
+ * serializer-resolution errors.
+ *
+ * Every line is independently well-formed and a line is omitted entirely — no placeholder, no empty
+ * slot — when the path that raised the error does not have that fact. The paths differ, and
+ * deliberately so:
+ *
+ * - the serializer key is on every path, since it is an argument of resolution itself;
+ * - the render edge is present only when a `rendersOne`/`rendersMany` led to the failing class. The
+ *   three root entry points (`Dream.serializationMap`, `Dream.displaySerialization` and
+ *   `buildSerializerPreloadPaths`) resolve a class the caller named directly, so nothing led there;
+ * - the declaring serializer is present only while preload paths and serialization maps are built.
+ *   `SerializerRenderer` holds the rendered attribute but not the serializer that declared it;
+ * - the STI base is present only where expanding one produced the class the error names.
+ */
+export default function serializerResolutionContextMessage(serializerKey, context) {
+    const lines = [];
+    if (serializerKey !== undefined)
+        lines.push(['serializer key', serializerKey]);
+    const edge = context?.edge;
+    if (edge)
+        lines.push([
+            'reached through',
+            edge.declaredBy
+                ? `${edge.type} \`${edge.associationName}\`, declared by ${edge.declaredBy}`
+                : `${edge.type} \`${edge.associationName}\``,
+        ]);
+    if (context?.stiBase)
+        lines.push(['expanded from', `the STI base ${context.stiBase}`]);
+    if (lines.length === 0)
+        return '';
+    return `
+
+Serializer resolution context:
+
+${lines.map(([label, value]) => `  ${`${label}:`.padEnd(LABEL_COLUMN_WIDTH)}${value}`).join('\n')}`;
+}
+/**
+ * Fixed rather than computed from the lines actually present, so that the same fact sits in the
+ * same column in every one of these errors — a reader comparing two failures is not also comparing
+ * two layouts.
+ */
+const LABEL_COLUMN_WIDTH = 'reached through: '.length;

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

@@ -54,7 +54,13 @@ export default function generateFactoryContent({ fullyQualifiedModelName, column
                 belongsToNames.push(attributeVariable);
                 belongsToTypedNames.push(`${attributeVariable}: ${associationModelName}`);
                 additionalImports.push(associationFactoryImportStatement);
-                associationCreationStatements.push(`${attributeVariable}: attrs.${attributeVariable} ? null : await create${associationModelName}(),`);
+                // The parens around `await` are what Prettier itself emits for an
+                // `await` operand of `??` (it parenthesizes unconditionally), and this
+                // string is written to the consumer's file verbatim — no formatting
+                // pass — so omitting them makes every freshly generated factory fail
+                // `prettier --check` in their project. See the Prettier fixed-point
+                // specs in spec/unit/cli/generateFactoryContent.spec.ts.
+                associationCreationStatements.push(`${attributeVariable}: attrs.${attributeVariable} ?? (await create${associationModelName}()),`);
                 break;
             }
             case 'encrypted':

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

@@ -175,19 +175,8 @@ export default function generateMigrationContent({ connectionName = 'default', t
         }
         return acc;
     }, { columnDefs: [], columnDrops: [], indexDefs: [] });
-    if (!table) {
-        return `\
-import { Kysely, sql } from 'kysely'
-
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-export async function up(db: Kysely<any>): Promise<void> {
-}
-
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-export async function down(db: Kysely<any>): Promise<void> {
-}\
-`;
-    }
+    if (!table)
+        return emptyMigrationContent();
     // An alter migration (either `-to-`/add or `-from-`/remove) with no valid
     // columns to add/drop would otherwise emit a bare `.alterTable(...).execute()`
     // with no column operation at all, which Postgres rejects at migration-run
@@ -207,6 +196,22 @@ export async function down(db: Kysely<any>): Promise<void> {
         !stiChildClassName) {
         throw new NoColumnsToAlterMigration(table, alterDirection, migrationName, alterMarker);
     }
+    // The placeholder table is the standalone `g:migration` markerless path (see
+    // MIGRATION_TABLE_NAME_PLACEHOLDER above): the migration name resolved no
+    // table, so there is nothing to alter. With no columns declared either, there
+    // is no column operation to scaffold, so emit genuinely empty `up`/`down`
+    // bodies for the developer to fill in rather than an
+    // `alterTable('<table-name>')` statement that cannot run as generated.
+    //
+    // The test is `columnsWithTypes`, deliberately, and not `columnDefs`: the two
+    // diverge. A declaration the reduce above filters out entirely (e.g.
+    // `comments:has_many`) leaves `columnDefs` empty while the user did type a
+    // column, and emptying the bodies there would silently discard it. Markerless
+    // *with* columns therefore keeps the placeholder scaffold — the table name is
+    // the only part the generator cannot work out, and `g:migration`'s help
+    // already documents that case as a stub to hand-edit.
+    if (altering && table === MIGRATION_TABLE_NAME_PLACEHOLDER && columnsWithTypes.length === 0)
+        return emptyMigrationContent();
     const citextExtension = requireCitextExtension
         ? `  await DreamMigrationHelpers.createExtension(db, 'citext')\n\n`
         : '';
@@ -273,6 +278,68 @@ ${downBody}
 }\
 `;
 }
+/**
+ * A migration file with nothing in it: correct imports, the standard `up`/`down`
+ * signatures, and empty bodies.
+ *
+ * Three deliberate departures from the scaffolded migrations above. All three
+ * exist so that the file this generator writes is clean the instant it lands in
+ * a consumer's project — under their formatter as well as their linter. See
+ * `spec/unit/cli/generateMigrationContent.spec.ts`
+ * ("the generated empty migration is clean under a consumer's tooling"), which
+ * runs this exact output through Prettier and through ESLint's
+ * `recommended` + `typescript-eslint recommended` and pins zero of both.
+ *
+ * - The bodies are `{}`, closed on the signature's own line, not `{\n}`, and
+ *   the file ends in a newline. Prettier collapses an empty block onto one line
+ *   and requires a final newline, so either spelling is a formatting violation
+ *   the moment it is written and fails `prettier --check` in the consumer's CI
+ *   (and this repo's own `pnpm lint`, which ends in `pnpm prettier . --check`);
+ *   `writeGeneratedFile` writes this string byte-for-byte with no formatting
+ *   pass. The final newline is why this template does not end with the
+ *   backslash line-continuation the scaffolded return above uses. (Those
+ *   scaffolds are missing their own final newline, which is pre-existing and
+ *   pinned by ~90 `toEqual` expectations across three spec files; it is not
+ *   this template's to fix. `generateFactoryContent` and
+ *   `generateUnitSpecContent` already terminate their output the way this one
+ *   now does.)
+ * - `sql` is left out of the import list. Every other generated migration
+ *   imports it unconditionally because most bodies need it, but an empty body
+ *   never does, and an unused import is an error under
+ *   `@typescript-eslint/no-unused-vars` in a file that would otherwise have
+ *   nothing to report.
+ * - `db` keeps its name — the developer's first keystroke in the body is going
+ *   to be `db.`, and dropping the parameter (with the `Kysely` import that only
+ *   it uses) would make them type both back — and the existing
+ *   `no-explicit-any` directive is widened to disable `no-unused-vars` too.
+ *   `db` is unused until the body is written, and `no-unused-vars` is
+ *   *error*-level under `typescript-eslint`'s `recommended` with
+ *   `args: 'after-used'`, so without the directive `psy g:migration <name> &&
+ *   pnpm lint` fails on a brand-new, untouched file. (The `await`-less `async`
+ *   needs nothing: `require-await` deliberately ignores empty function bodies.)
+ *   An `_db` rename is not a substitute: `no-unused-vars` sets no
+ *   `argsIgnorePattern` by default, so `_db` reports too, and the developer
+ *   then has to rename it back.
+ *
+ *   The cost of the widened directive is that the `no-unused-vars` half goes
+ *   stale once the body uses `db`, which ESLint 9 reports via its default
+ *   `reportUnusedDisableDirectives`. That is a *warning* rather than the two
+ *   *errors* it replaces, it lands in the file the developer is already
+ *   editing, and `eslint --fix` removes just that rule name from the directive
+ *   and leaves `no-explicit-any` in place — so it is strictly the cheaper of
+ *   the two, in severity and in effort.
+ */
+function emptyMigrationContent() {
+    return `\
+import { Kysely } from 'kysely'
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unused-vars
+export async function up(db: Kysely<any>): Promise<void> {}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unused-vars
+export async function down(db: Kysely<any>): Promise<void> {}
+`;
+}
 function getAttributeType(attributeType, descriptors) {
     switch (attributeType) {
         case 'string':

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

@@ -0,0 +1,41 @@
+import DreamCLI from '../../cli/index.js';
+/**
+ * Runs the type/schema sync a command performs after its own work has already
+ * succeeded, and — when that sync fails — logs a message naming what completed
+ * and naming the sync as the step that failed, before re-raising the original
+ * error untouched.
+ *
+ * Without this, a failing sync surfaces a bare sync error immediately after
+ * e.g. `db:rollback`, which reads as a failed rollback even though the
+ * rollback itself is already committed.
+ *
+ * The original error is re-thrown rather than wrapped, so the error a caller
+ * sees, and the command's non-zero exit status, are exactly what they were
+ * before. Callers keep their own `EnvInternal.isTest` / `--skip-sync` guards:
+ * this wrapper takes the sync call, not the decision to make it.
+ */
+export default async function syncWithFailureContext({ commandName, completedWork, didNotRun, recoveryAdvice }, sync) {
+    try {
+        await sync();
+    }
+    catch (error) {
+        DreamCLI.logger.log(syncFailureMessage({ commandName, completedWork, didNotRun, recoveryAdvice }));
+        throw error;
+    }
+}
+/**
+ * @internal
+ *
+ * Builds the explanatory message logged when a post-work sync fails.
+ */
+export function syncFailureMessage({ commandName, completedWork, didNotRun, recoveryAdvice, }) {
+    const skipped = didNotRun ? `; ${didNotRun}` : '';
+    const recovery = recoveryAdvice ?? 'run `sync` on its own';
+    return `
+${commandName}: the sync step failed — not ${commandName}'s own work.
+
+${completedWork}. What failed afterward is the sync that ${commandName} runs to regenerate the auto-generated type and schema files${skipped}.
+
+The sync error itself is printed alongside this message. Once it is resolved, ${recovery}.
+`;
+}

package/dist/cjs/src/serializer/SerializerRenderer.js

@@ -97,7 +97,7 @@ export default class SerializerRenderer {
                     const associatedObject = data[attribute.name];
                     let serializer = null;
                     if (associatedObject) {
-                        serializer = serializerForAssociatedObject(associatedObject, attribute.options);
+                        serializer = serializerForAssociatedObject(associatedObject, attribute.options, renderTimeResolutionContext(attribute.options, 'rendersOne', attribute.name));
                     }
                     else if (attribute.options.flatten) {
                         /**
@@ -146,8 +146,12 @@ export default class SerializerRenderer {
                     const associatedObjects = data[attribute.name];
                     if (!associatedObjects)
                         throw new RendersManyMustReceiveArray(attribute, associatedObjects);
+                    // Hoisted out of the map: the context is identical for every element, is immutable, and is
+                    // read only while an error message is being built, so one object serves the whole
+                    // collection rather than one per element.
+                    const resolutionContext = renderTimeResolutionContext(attribute.options, 'rendersMany', attribute.name);
                     accumulator[outputAttributeName] = compact(associatedObjects).map(associatedObject => {
-                        const serializer = serializerForAssociatedObject(associatedObject, attribute.options);
+                        const serializer = serializerForAssociatedObject(associatedObject, attribute.options, resolutionContext);
                         return (
                         // passthrough data going into the serializer is the argument that gets
                         // used in the custom attribute callback function
@@ -206,8 +210,32 @@ function _applyRenderingOptionsToAttribute(data, value, attributeName, options,
         return round(value, precision);
     return value ?? null;
 }
-function serializerForAssociatedObject(associatedObject, options) {
+/**
+ * `resolutionContext` is error-only: it names the rendersOne/rendersMany this object is being
+ * rendered through, so that a serializer that cannot be resolved for it says which association led
+ * here rather than only which class failed. It is `undefined` whenever no resolution will happen —
+ * see `renderTimeResolutionContext`.
+ */
+function serializerForAssociatedObject(associatedObject, options, resolutionContext) {
     if (options.serializer)
         return options.serializer;
-    return inferSerializerFromDreamOrViewModel(associatedObject, options.serializerKey);
+    return inferSerializerFromDreamOrViewModel(associatedObject, options.serializerKey, resolutionContext);
+}
+/**
+ * Builds the error-only resolution context for one rendered association, or `undefined` when the
+ * render will not resolve a serializer at all.
+ *
+ * Rendering is a hot path — once per rendered association per request, and `rendersMany` renders one
+ * element at a time from a collection — so this deliberately allocates nothing it cannot use:
+ * `serializerForAssociatedObject` returns `options.serializer` before resolving anything when the
+ * association declares its own serializer, and in that case there is no resolution to describe.
+ * Callers build this once per rendered association and share it across every element.
+ *
+ * The renderer holds no serializer object, so the edge carries no `declaredBy` — see
+ * `SerializerResolutionContext`.
+ */
+function renderTimeResolutionContext(options, type, associationName) {
+    if (options.serializer)
+        return undefined;
+    return { edge: { type, associationName } };
 }

package/dist/cjs/src/serializer/helpers/inferSerializerFromDreamOrViewModel.js

@@ -9,33 +9,51 @@ import expandStiClasses from '../../helpers/sti/expandStiClasses.js';
 import uniq from '../../helpers/uniq.js';
 import isDreamSerializer from './isDreamSerializer.js';
 export const DEFAULT_SERIALIZER_KEY = 'default';
-export default function inferSerializerFromDreamOrViewModel(obj, serializerKey = DEFAULT_SERIALIZER_KEY) {
+/**
+ * `resolutionContext` says how resolution reached `obj` — the `rendersOne`/`rendersMany` edge that
+ * led here, and the STI base it was expanded from. It is threaded down purely so that the errors
+ * below can name the route instead of only the class, and it is optional so that a caller with no
+ * route to describe (and every existing caller outside this repo) is unaffected. See
+ * `SerializerResolutionContext`.
+ */
+export default function inferSerializerFromDreamOrViewModel(obj, serializerKey = DEFAULT_SERIALIZER_KEY, resolutionContext) {
     if (!obj)
         return null;
     const serializers = obj.serializers;
     if (!serializers)
-        throw new MissingSerializersDefinition(obj);
+        throw new MissingSerializersDefinition(obj, serializerKey, resolutionContext);
     const serializerOrGlobalName = serializers[serializerKey];
     if (!serializerOrGlobalName)
-        throw new MissingSerializersDefinitionForKey(obj, serializerKey);
+        throw new MissingSerializersDefinitionForKey(obj, serializerKey, resolutionContext);
     if (isDreamSerializer(serializerOrGlobalName))
         return serializerOrGlobalName;
     const globalName = serializerOrGlobalName;
     const dreamApp = DreamApp.getOrFail();
     const serializer = dreamApp.serializers[globalName];
     if (!serializer)
-        throw new NoGlobalSerializerForSpecifiedKey(obj, serializerKey, globalName);
+        throw new NoGlobalSerializerForSpecifiedKey(obj, serializerKey, globalName, resolutionContext);
     if (!isDreamSerializer(serializer))
-        throw new NonDreamSerializerDerivedFromGlobalSerializerForSpecifiedKey(obj, serializerKey, globalName, serializer);
+        throw new NonDreamSerializerDerivedFromGlobalSerializerForSpecifiedKey(obj, serializerKey, globalName, serializer, resolutionContext);
     return serializer;
 }
-export function inferSerializersFromDreamClassOrViewModelClass(classDef, serializerKey = undefined) {
+export function inferSerializersFromDreamClassOrViewModelClass(classDef, serializerKey = undefined, resolutionContext) {
     if (!classDef)
         return [];
     const classes = expandStiClasses(classDef);
-    const serializers = classes.map(classDef => inferSerializerFromDreamOrViewModel(classDef.prototype, serializerKey));
+    // This is the one place that knows *whether* the class an error ends up naming came from STI
+    // expansion: below this line the class the caller passed is gone, replaced by one child per
+    // iteration, and every downstream error names a child. Identity rather than `isSTIBase` because
+    // `classDef` may be a ViewModelClass, which `expandStiClasses` hands straight back.
+    const expandedFromStiBase = classes.length !== 1 || classes[0] !== classDef;
+    const childResolutionContext = expandedFromStiBase
+        ? { ...resolutionContext, stiBase: stiBaseName(classDef) }
+        : resolutionContext;
+    const serializers = classes.map(classDef => inferSerializerFromDreamOrViewModel(classDef.prototype, serializerKey, childResolutionContext));
     return uniq(compact(serializers));
 }
+function stiBaseName(classDef) {
+    return classDef.sanitizedName ?? classDef.name;
+}
 /**
  * As `inferSerializersFromDreamClassOrViewModelClass`, but guarantees a non-empty result.
  *
@@ -51,9 +69,9 @@ export function inferSerializersFromDreamClassOrViewModelClass(classDef, seriali
  * preload-path building and serialization display — so that they raise one typed error between
  * them.
  */
-export function inferSerializersFromDreamClassOrViewModelClassOrFail(classDef, serializerKey) {
-    const serializers = inferSerializersFromDreamClassOrViewModelClass(classDef, serializerKey);
+export function inferSerializersFromDreamClassOrViewModelClassOrFail(classDef, serializerKey, resolutionContext) {
+    const serializers = inferSerializersFromDreamClassOrViewModelClass(classDef, serializerKey, resolutionContext);
     if (serializers.length === 0)
-        throw new NoSerializersResolvedForKey(classDef, serializerKey);
+        throw new NoSerializersResolvedForKey(classDef, serializerKey, resolutionContext);
     return serializers;
 }

package/dist/cjs/src/serializer/helpers/serializerForAssociatedClass.js

@@ -28,5 +28,10 @@ export function serializerForAssociatedClass(object, associationName, options) {
     // would flatten. Unioning every child's serializer here — which is what buildSerializerPreloadPaths
     // does for preload paths — is meaningless: exactly one set of keys can be flattened into the
     // payload.
-    return inferSerializersFromDreamClassOrViewModelClass(associatedClass, options.serializerKey)[0] ?? null;
+    return (inferSerializersFromDreamClassOrViewModelClass(associatedClass, options.serializerKey, {
+        // Reached only from SerializerRenderer's rendersOne branch, so the edge type is fixed. No
+        // declaring serializer: the renderer holds the rendered attribute, not the serializer that
+        // declared it.
+        edge: { type: 'rendersOne', associationName },
+    })[0] ?? null);
 }

package/dist/cjs/src/serializer/helpers/serializerGlobalName.js

@@ -0,0 +1,16 @@
+/**
+ * @internal
+ *
+ * The single reader of a serializer's `globalName`.
+ *
+ * Serializers are plain functions; `globalName` is stamped onto them by `importSerializers` when the
+ * app loads them, so the property is not on any serializer type and every reader would otherwise
+ * have to invent its own cast — three different spellings of it existed before this helper.
+ *
+ * `undefined` is a legitimate answer: a serializer built inline (a spec, or a `{ serializer }`
+ * option) is never stamped. Callers decide what that means for them — the resolution-context message
+ * simply drops the declarer.
+ */
+export default function serializerGlobalName(serializer) {
+    return serializer.globalName;
+}

package/dist/esm/src/Dream.js

@@ -49,6 +49,7 @@ import cloneDeepSafe from './helpers/cloneDeepSafe.js';
 import isJsonColumn from './helpers/db/types/isJsonColumn.js';
 import notEqual from './helpers/notEqual.js';
 import { inferSerializersFromDreamClassOrViewModelClassOrFail } from './serializer/helpers/inferSerializerFromDreamOrViewModel.js';
+import serializerGlobalName from './serializer/helpers/serializerGlobalName.js';
 export default class Dream {
     DB;
     /**
@@ -580,8 +581,10 @@ export default class Dream {
         // One line per serializer: for an STI base the displayed tree is the union across its children,
         // so naming a single child's serializer under the base's own name would misattribute the tree.
         serializers.forEach(serializer => {
+            // Interpolated rather than defaulted so the printed line is unchanged for a serializer with no
+            // globalName; naming inline serializers in this tree is its own change.
             // eslint-disable-next-line no-console
-            console.log(yoctocolors.gray(serializer.globalName));
+            console.log(yoctocolors.gray(`${serializerGlobalName(serializer)}`));
         });
         return this.recursiveSerializationMap(serializers, {
             forDisplay: true,
@@ -667,6 +670,12 @@ export default class Dream {
      *   * foreign key fields for belongs to associations (these should usually be verified before being set)
      *   * type fields corresponding to polymorphic associations
      *
+     * @internal
+     *
+     * Not part of the public API. Psychic reaches it through the bracketed
+     * back-door (`dreamClass['paramSafeColumnsOrFallback']()`), the same escape
+     * hatch used for other Dream internals such as `virtualAttributes`.
+     *
      * @returns A subset of columns for the given dream class
      */
     static paramSafeColumnsOrFallback() {

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

@@ -5,6 +5,7 @@ import DreamApp from '../dream-app/index.js';
 import Encrypt from '../encrypt/index.js';
 import SspawnRequiresDevelopmentOrTest from '../errors/SspawnRequiresDevelopmentOrTest.js';
 import generateDream from '../helpers/cli/generateDream.js';
+import syncWithFailureContext from '../helpers/cli/syncWithFailureContext.js';
 import EnvInternal from '../helpers/EnvInternal.js';
 import loadRepl from '../helpers/loadRepl.js';
 import DreamCliLogger from './logger/DreamCliLogger.js';
@@ -129,7 +130,9 @@ ${INDENT}  create-many-to-many-posts-users         # WRONG: selects 'many_posts_
 ${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`;
+${INDENT}    # with no columns, generates empty up/down methods to
+${INDENT}    # write by hand; with columns, scaffolds
+${INDENT}    # alterTable('<table-name>') to hand-edit`;
 export default class DreamCLI {
     /**
      * Starts the Dream console
@@ -184,7 +187,9 @@ ${INDENT}  # Remove columns (include -from-<table_name>; columns are described w
 ${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 -to-/-from- marker — scaffolds alterTable('<table-name>') to hand-edit)
+${INDENT}  # General schema change (no -to-/-from- marker — with no columns, generates
+${INDENT}  # empty up/down methods to write by hand; with columns, scaffolds
+${INDENT}  # alterTable('<table-name>') to hand-edit)
 ${INDENT}  pnpm psy g:migration create-unique-index-on-invitations`)
             .argument('<migrationName>', migrationNameArgumentDescription)
             .option('--connection-name <connectionName>', 'the database connection to use for this migration. Only needed for multi-database setups; defaults to "default"')
@@ -345,7 +350,11 @@ ${INDENT}  pnpm psy db:migrate`)
             await initializeDreamApp({ bypassDreamIntegrityChecks: true });
             await DreamBin.dbMigrate();
             if (EnvInternal.isTest && !skipSync) {
-                await DreamBin.sync(onSync);
+                await syncWithFailureContext({
+                    commandName: 'db:migrate',
+                    completedWork: 'Every pending migration ran successfully',
+                    recoveryAdvice: 'run `sync` on its own, or re-run `db:migrate` — the migrations it already applied are not re-applied, so it goes straight back to the sync',
+                }, async () => await DreamBin.sync(onSync));
             }
             process.exit();
         });
@@ -362,7 +371,13 @@ ${INDENT}  pnpm psy db:rollback --steps=3    # rolls back the last 3 migrations`
             await initializeDreamApp({ bypassDreamIntegrityChecks: true });
             await DreamBin.dbRollback({ steps });
             if (EnvInternal.isTest && !skipSync) {
-                await DreamBin.sync(onSync);
+                await syncWithFailureContext({
+                    commandName: 'db:rollback',
+                    completedWork: 'The rollback completed successfully and is already committed',
+                    // never `re-run db:rollback` here: the rollback is already
+                    // committed, so a second run rolls back a further migration
+                    recoveryAdvice: 'run `sync` on its own. Do not re-run `db:rollback` — the rollback it would perform is a further one, undoing a migration you did not ask to undo',
+                }, async () => await DreamBin.sync(onSync));
             }
             process.exit();
         });
@@ -409,7 +424,18 @@ ${INDENT}Warning: all existing data will be lost. The seed file (db/seed.ts) wil
                 logPrefix: ' ',
                 logPrefixColor: 'green',
             });
-            await DreamBin.sync(onSync);
+            await syncWithFailureContext({
+                commandName: 'db:reset',
+                completedWork: 'db:drop, db:create and db:migrate all completed successfully',
+                didNotRun: 'db:seed, which db:reset runs after the sync, did not run',
+                // the two routes are not interchangeable, so the second one names
+                // the env var it needs: db:reset seeds by calling the app's seed
+                // hook directly (below), while the `db:seed` *command* refuses to
+                // seed under NODE_ENV=test unless DREAM_SEED_DB_IN_TEST=1 — and
+                // NODE_ENV=test is the only environment DreamBin.sync does any
+                // work in, so it is the only environment this advice is printed in
+                recoveryAdvice: 're-run `db:reset`, which seeds directly and so picks up the skipped seeding step, or run `sync` on its own followed by `DREAM_SEED_DB_IN_TEST=1 db:seed` — this sync only runs under `NODE_ENV=test`, and a bare `db:seed` does not seed there',
+            }, async () => await DreamBin.sync(onSync));
             DreamCLI.logger.log(arrows, { logPrefix: ' ' });
             DreamCLI.logger.log(colorize('db:seed', { color: 'green' }), {
                 logPrefix: ' ',