@db3.ai/app 0.1.0-beta.1 → 0.1.0-beta.4

package/dist/auth/providers/PasswordAuthProvider.js

@@ -1,5 +1,11 @@
+import { randomBytes, randomUUID } from 'node:crypto';
 import { AuthProvider, PASSWORD_AUTH_PROVIDER } from '../AuthProvider.js';
 import { defaultPasswordHash } from '../passwordHash.js';
+import { PasswordSuspendedError } from '../PasswordSuspendedError.js';
+import { PasswordLoginAttempt } from '../PasswordLoginAttempt.js';
+const DEFAULT_MAX_FAILED_ATTEMPTS = 20;
+/** Valid default-cost scrypt value used only for unknown-identity timing parity. */
+const DUMMY_PASSWORD_HASH = 'scrypt$1$16384$8$1$64$0123456789abcdef0123456789abcdef$' + '00'.repeat(64);
 /**
  * Provider driver for first-party email and password authentication.
  *
@@ -12,6 +18,8 @@ export class PasswordAuthProvider {
     IdentityModel;
     ProviderModel;
     passwordHash;
+    #suspension;
+    #dummyHash;
     /**
      * Creates a password auth provider.
      *
@@ -21,25 +29,91 @@ export class PasswordAuthProvider {
         this.IdentityModel = options.identityModel;
         this.ProviderModel = options.providerModel ?? AuthProvider;
         this.passwordHash = options.passwordHash ?? defaultPasswordHash;
+        this.#suspension = resolveSuspension(options.suspension);
     }
     /**
-     * Verifies submitted password credentials against the stored provider row.
+     * Verifies credentials under the identity's durable attempt lock.
      *
-     * @param input - Submitted password credential payload.
-     * @returns Normalized password provider profile, or null when verification fails.
+     * Unknown identities receive the same failed-attempt accounting and password
+     * hashing work as existing accounts. Suspension persists until verified
+     * password recovery; a correct password cannot clear a suspended identity.
+     *
+     * @param input - Submitted password credentials.
+     * @returns Verified provider profile, or null for an invalid password.
+     * @throws {PasswordSuspendedError} When this identity needs password recovery.
      */
     async verify(input) {
         if (!isPasswordCredentials(input))
             return null;
         const identity = normalizeIdentity(input[this.IdentityModel.identityField]);
-        if (!identity)
+        if (!identity || identity.length > 255)
             return null;
+        if (!this.#suspension)
+            return this.#verifyPassword(identity, input.password);
+        // Return the refusal from the transaction so the threshold update commits
+        // before the public error is thrown.
+        const result = await PasswordLoginAttempt.withIdentityLock(identity, async (attempt) => {
+            if (attempt.suspendedAt)
+                return new PasswordSuspendedError();
+            const profile = await this.#verifyPassword(identity, input.password);
+            if (profile) {
+                attempt.failedAttempts = 0;
+            }
+            else {
+                attempt.failedAttempts += 1;
+                if (attempt.failedAttempts >= this.#suspension.maxFailedAttempts) {
+                    attempt.suspendedAt = new Date();
+                    attempt.suspensionId = randomUUID();
+                }
+            }
+            await attempt.save();
+            return attempt.suspendedAt ? new PasswordSuspendedError({ attemptId: String(attempt.id), suspensionId: attempt.suspensionId }) : profile;
+        });
+        if (result instanceof PasswordSuspendedError)
+            throw result;
+        return result;
+    }
+    /**
+     * Performs equivalent hashing work for known and unknown identities.
+     * @param identity - Normalized submitted identity.
+     * @param password - Submitted plaintext password, never persisted.
+     * @returns Profile only when an existing password credential matches.
+     */
+    async #verifyPassword(identity, password) {
         const provider = await this.findProvider(identity);
-        if (!provider)
-            return null;
-        if (!await provider.verifyPassword(input.password, this.passwordHash))
+        // SQL collations may match distinct identities (for example accented text).
+        // Only our exact normalized key may reach the credential verification path.
+        if (!provider || normalizeIdentity(provider.providerUserId) !== identity) {
+            const dummy = this.passwordHash === defaultPasswordHash
+                ? DUMMY_PASSWORD_HASH
+                : await (this.#dummyHash ??= this.passwordHash.hash(randomBytes(32).toString('hex')).catch(error => {
+                    this.#dummyHash = undefined;
+                    throw error;
+                }));
+            await this.passwordHash.verify(password, dummy);
             return null;
-        return profileFromProvider(provider);
+        }
+        return await provider.verifyPassword(password, this.passwordHash) ? profileFromProvider(provider) : null;
+    }
+    /**
+     * Replaces a verified owner's password and clears suspension atomically.
+     * Called by Auth only after a usable, identity-matched recovery token is locked.
+     * @param user - Account whose email recovery proof was verified.
+     * @param password - Replacement plaintext password.
+     * @returns Saved password provider.
+     */
+    async recoverPassword(user, password) {
+        const identity = this.userIdentityValue(user);
+        if (!identity)
+            throw new Error('Cannot recover a password without an identity.');
+        return PasswordLoginAttempt.withIdentityLock(identity, async (attempt) => {
+            const provider = await this.setPassword(user, password);
+            attempt.failedAttempts = 0;
+            attempt.suspendedAt = null;
+            attempt.suspensionId = null;
+            await attempt.save();
+            return provider;
+        });
     }
     /**
      * Creates or replaces the password provider for a user.
@@ -193,3 +267,17 @@ function profileFromProvider(provider) {
         profile: provider.profile,
     };
 }
+/**
+ * Resolves the failed-attempt threshold and rejects invalid startup config.
+ * @param options - Identity suspension policy, or false to disable accounting.
+ * @returns Validated threshold, or null when disabled.
+ */
+function resolveSuspension(options) {
+    if (options === false)
+        return null;
+    const maxFailedAttempts = options?.maxFailedAttempts ?? DEFAULT_MAX_FAILED_ATTEMPTS;
+    if (!Number.isSafeInteger(maxFailedAttempts) || maxFailedAttempts < 1 || maxFailedAttempts > 1_000_000) {
+        throw new Error('Password suspension maxFailedAttempts must be an integer between 1 and 1000000.');
+    }
+    return { maxFailedAttempts };
+}

package/dist/auth/providers/resolveAuthProviders.js

@@ -45,6 +45,7 @@ function resolveAuthProvider(provider, config, factoryOptions) {
                 identityModel: factoryOptions.identityModel,
                 providerModel: factoryOptions.providerModel,
                 passwordHash: factoryOptions.passwordHash,
+                suspension: options.suspension,
             });
         case GOOGLE_AUTH_PROVIDER:
             return new GoogleAuthProvider(googleOptionsFromConfig(options));

package/dist/cli/Cli.d.ts

@@ -8,6 +8,8 @@ export declare class Cli {
      * @param options - Root directory and output adapters.
      */
     constructor(config: cli.CliConfig, options?: cli.CliOptions);
+    /** Returns detached metadata without booting the app or exposing executable handlers. */
+    commands(): cli.CliCommandInfo[];
     /**
      * Runs one invocation, printing help without app startup and closing a created app on failure too.
      * @param argv - Arguments after the executable name.

package/dist/cli/Cli.js

@@ -35,6 +35,14 @@ export class Cli {
             this.#commands.set(command.name, command);
         }
     }
+    /** Returns detached metadata without booting the app or exposing executable handlers. */
+    commands() {
+        return [...this.#commands.values()].map(command => ({
+            name: command.name, description: command.description,
+            arguments: (command.arguments ?? []).map(argument => ({ ...argument })),
+            interactive: command.interactive ?? false,
+        }));
+    }
     /**
      * Runs one invocation, printing help without app startup and closing a created app on failure too.
      * @param argv - Arguments after the executable name.

package/dist/cli/commands/repl.js

@@ -8,7 +8,8 @@ import { runRepl } from '../runRepl.js';
  */
 export function createReplCommand(loadModels, options) {
     return {
-        name: 'repl', description: 'Explore the application and its models in an interactive terminal.',
+        name: 'repl',
+        interactive: true, description: 'Explore the application and its models in an interactive terminal.',
         /** Boots the app without an HTTP listener and keeps it alive until REPL exit. */
         async run(context) {
             const application = await context.app();

package/dist/cli/contracts/CliCommand.d.ts

@@ -25,6 +25,8 @@ export interface CliCommand {
     description: string;
     /** Positional argument declarations used for validation and help. */
     arguments?: readonly CliArgument[];
+    /** Requires an interactive terminal session; visual one-shot runners must exclude it. */
+    interactive?: boolean;
     /** Executes the operation; return a nonzero status for a reported failure. */
     run(context: CliCommandContext): number | void | Promise<number | void>;
 }

package/dist/cli/contracts/CliCommandInfo.d.ts

@@ -0,0 +1,12 @@
+import type { CliArgument } from './CliCommand.js';
+/** Serializable command metadata for explorers; never includes executable handlers or configuration. */
+export interface CliCommandInfo {
+    /** Unique registered command name. */
+    name: string;
+    /** Human-readable purpose shown in help and visual explorers. */
+    description: string;
+    /** Ordered positional inputs accepted by the CLI. */
+    arguments: readonly CliArgument[];
+    /** Interactive commands require a terminal session instead of a one-shot form. */
+    interactive: boolean;
+}

package/dist/cli/contracts/CliCommandInfo.js

@@ -0,0 +1 @@
+export {};

package/dist/cli/contracts/index.d.ts

@@ -3,3 +3,4 @@ export type * from './CliConfig.js';
 export type * from './CliOptions.js';
 export type * from './CommandDefinition.js';
 export type * from './ReplOptions.js';
+export type * from './CliCommandInfo.js';

package/dist/cli/index.d.ts

@@ -3,3 +3,4 @@ export * from './Cli.js';
 export * from './runDb3.js';
 export * from './defineCommand.js';
 export * from './runRepl.js';
+export * from './listDb3Commands.js';

package/dist/cli/index.js

@@ -3,3 +3,4 @@ export * from './Cli.js';
 export * from './runDb3.js';
 export * from './defineCommand.js';
 export * from './runRepl.js';
+export * from './listDb3Commands.js';

package/dist/cli/listDb3Commands.d.ts

@@ -0,0 +1,8 @@
+import type * as cli from './contracts/index.js';
+/**
+ * Discovers registered and built-in commands without creating the application.
+ * Configuration imports must remain free of startup side effects, as for CLI help.
+ * @param options - App root containing server/cli.config.ts, .mjs or .js.
+ * @returns Serializable command descriptions, including terminal-only capabilities.
+ */
+export declare function listDb3Commands(options?: Pick<cli.CliOptions, 'directory'>): Promise<cli.CliCommandInfo[]>;

package/dist/cli/listDb3Commands.js

@@ -0,0 +1,10 @@
+import { withDb3Cli } from './withDb3Cli.js';
+/**
+ * Discovers registered and built-in commands without creating the application.
+ * Configuration imports must remain free of startup side effects, as for CLI help.
+ * @param options - App root containing server/cli.config.ts, .mjs or .js.
+ * @returns Serializable command descriptions, including terminal-only capabilities.
+ */
+export async function listDb3Commands(options = {}) {
+    return withDb3Cli(options, async (runner) => runner.commands());
+}

package/dist/cli/runDb3.d.ts

@@ -1,11 +1,8 @@
 import type * as cli from './contracts/index.js';
 /**
- * Loads app registration and runs the framework CLI from source or an installed package.
- *
- * TypeScript config loading supports the same extensionless imports as the starter.
- * No HTTP listener is started. Help and queue:make-job do not create the app.
+ * Runs registered framework commands with app-owned startup and cleanup.
  * @param argv - Arguments after db3.
- * @param options - Application root and optional output adapters.
- * @returns Exit status to assign to process.exitCode.
+ * @param options - Application root and terminal adapters.
+ * @returns Process-compatible exit status without exiting the process.
  */
 export declare function runDb3(argv: readonly string[], options?: cli.CliOptions): Promise<number>;

package/dist/cli/runDb3.js

@@ -1,70 +1,16 @@
-import { access } from 'node:fs/promises';
-import { randomUUID } from 'node:crypto';
-import { resolve } from 'node:path';
-import { pathToFileURL } from 'node:url';
-import { register } from 'tsx/esm/api';
-import { Cli } from './Cli.js';
-import { createReplCommand } from './commands/repl.js';
+import { withDb3Cli } from './withDb3Cli.js';
 /**
- * Loads app registration and runs the framework CLI from source or an installed package.
- *
- * TypeScript config loading supports the same extensionless imports as the starter.
- * No HTTP listener is started. Help and queue:make-job do not create the app.
+ * Runs registered framework commands with app-owned startup and cleanup.
  * @param argv - Arguments after db3.
- * @param options - Application root and optional output adapters.
- * @returns Exit status to assign to process.exitCode.
+ * @param options - Application root and terminal adapters.
+ * @returns Process-compatible exit status without exiting the process.
  */
 export async function runDb3(argv, options = {}) {
-    const loader = register({ namespace: `db3-cli-${randomUUID()}` });
     try {
-        const { queueCommands } = await import('../queue/commands/index.js');
-        const directory = resolve(options.directory ?? process.cwd());
-        const configModule = await loadAppModule(directory, 'server/cli.config', loader.import);
-        const config = configModule ? configModule.default : { commands: [] };
-        // Validate app config before combining it with commands that need no app bootstrap.
-        if (!config || !Array.isArray(config.commands))
-            throw new Error('CLI configuration must export a commands array.');
-        const repl = createReplCommand(async () => loadReplModels(directory, loader.import), options);
-        return await new Cli({ ...config, commands: [repl, ...queueCommands, ...config.commands] }, { ...options, directory }).run(argv);
+        return await withDb3Cli(options, runner => runner.run(argv));
     }
     catch (error) {
         (options.writeError ?? console.error)(error instanceof Error ? error.message : 'Unable to load CLI configuration.');
         return 1;
     }
-    finally {
-        await loader.unregister();
-    }
-}
-/** Loads an optional conventional app module without hiding errors from its imports. */
-async function loadAppModule(directory, path, importModule) {
-    for (const extension of ['ts', 'mjs', 'js']) {
-        const file = resolve(directory, `${path}.${extension}`);
-        try {
-            await access(file);
-        }
-        catch (error) {
-            if (error.code === 'ENOENT')
-                continue;
-            throw error;
-        }
-        return importModule(pathToFileURL(file).href, import.meta.url);
-    }
-    return undefined;
-}
-/** Exposes named model constructors from the same registry used by app migrations. */
-async function loadReplModels(directory, importModule) {
-    const module = await loadAppModule(directory, 'server/database/models', importModule);
-    if (!module)
-        return {};
-    if (!Array.isArray(module.models))
-        throw new Error('server/database/models must export a models array for the REPL.');
-    const models = Object.create(null);
-    for (const model of module.models) {
-        if (typeof model !== 'function' || !/^[A-Za-z_$][\w$]*$/.test(model.name))
-            throw new Error('REPL models must be named constructors.');
-        if (['app', 'models', '__proto__', 'constructor', 'prototype'].includes(model.name) || Object.hasOwn(models, model.name))
-            throw new Error(`Duplicate or reserved REPL model name: ${model.name}`);
-        models[model.name] = model;
-    }
-    return models;
 }

package/dist/cli/withDb3Cli.d.ts

@@ -0,0 +1,4 @@
+import { Cli } from './Cli.js';
+import type * as cli from './contracts/index.js';
+/** Loads one app's command registry and releases its TypeScript loader after use. */
+export declare function withDb3Cli<T>(options: cli.CliOptions, use: (runner: Cli) => Promise<T>): Promise<T>;

package/dist/cli/withDb3Cli.js

@@ -0,0 +1,60 @@
+import { access } from 'node:fs/promises';
+import { randomUUID } from 'node:crypto';
+import { resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { register } from 'tsx/esm/api';
+import { Cli } from './Cli.js';
+import { createReplCommand } from './commands/repl.js';
+// Cache the import before scoped loaders alter hooks; avoid the CLI/Queue barrel cycle.
+let queueModule;
+/** Loads one app's command registry and releases its TypeScript loader after use. */
+export async function withDb3Cli(options, use) {
+    const { queueCommands } = await (queueModule ??= import('../queue/commands/index.js'));
+    const loader = register({ namespace: `db3-cli-${randomUUID()}` });
+    try {
+        const directory = resolve(options.directory ?? process.cwd());
+        const configModule = await loadAppModule(directory, 'server/cli.config', loader.import);
+        const config = configModule ? configModule.default : { commands: [] };
+        // Validate app config before combining it with commands that need no app bootstrap.
+        if (!config || !Array.isArray(config.commands))
+            throw new Error('CLI configuration must export a commands array.');
+        const repl = createReplCommand(async () => loadReplModels(directory, loader.import), options);
+        return await use(new Cli({ ...config, commands: [repl, ...queueCommands, ...config.commands] }, { ...options, directory }));
+    }
+    finally {
+        await loader.unregister();
+    }
+}
+/** Loads an optional conventional app module without hiding errors from its imports. */
+async function loadAppModule(directory, path, importModule) {
+    for (const extension of ['ts', 'mjs', 'js']) {
+        const file = resolve(directory, `${path}.${extension}`);
+        try {
+            await access(file);
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                continue;
+            throw error;
+        }
+        return importModule(pathToFileURL(file).href, import.meta.url);
+    }
+    return undefined;
+}
+/** Exposes named model constructors from the same registry used by app migrations. */
+async function loadReplModels(directory, importModule) {
+    const module = await loadAppModule(directory, 'server/database/models', importModule);
+    if (!module)
+        return {};
+    if (!Array.isArray(module.models))
+        throw new Error('server/database/models must export a models array for the REPL.');
+    const models = Object.create(null);
+    for (const model of module.models) {
+        if (typeof model !== 'function' || !/^[A-Za-z_$][\w$]*$/.test(model.name))
+            throw new Error('REPL models must be named constructors.');
+        if (['app', 'models', '__proto__', 'constructor', 'prototype'].includes(model.name) || Object.hasOwn(models, model.name))
+            throw new Error(`Duplicate or reserved REPL model name: ${model.name}`);
+        models[model.name] = model;
+    }
+    return models;
+}

package/dist/db/ActiveQueryBuilder.d.ts

@@ -132,6 +132,14 @@ export declare class ActiveQueryBuilder<TRecord extends ActiveRecord> {
      * Adds field-aware ordering.
      */
     orderBy(fieldName: string, direction?: 'asc' | 'desc'): this;
+    /**
+     * Adds SELECT ... FOR UPDATE while retaining typed ActiveRecord results.
+     * Execute inside a transaction; locks are released on commit or rollback.
+     * This delegates to Knex and does not start or finish a transaction.
+     * @returns This query for further filtering or execution.
+     * @example await app().db.transaction(async () => { const user = await User.where('id', id).forUpdate().first(); });
+     */
+    forUpdate(): this;
     /**
      * Limits the number of returned records.
      */

package/dist/db/ActiveQueryBuilder.js

@@ -208,6 +208,17 @@ export class ActiveQueryBuilder {
         this.qb.orderBy(this.qualifiedColumn(field), direction);
         return this;
     }
+    /**
+     * Adds SELECT ... FOR UPDATE while retaining typed ActiveRecord results.
+     * Execute inside a transaction; locks are released on commit or rollback.
+     * This delegates to Knex and does not start or finish a transaction.
+     * @returns This query for further filtering or execution.
+     * @example await app().db.transaction(async () => { const user = await User.where('id', id).forUpdate().first(); });
+     */
+    forUpdate() {
+        this.qb.forUpdate();
+        return this;
+    }
     /**
      * Limits the number of returned records.
      */

package/dist/db/ActiveRecord.d.ts

@@ -204,6 +204,12 @@ export declare abstract class ActiveRecord {
      * Returns the database connection for the current ActiveRecord operation.
      */
     static getDb(): Knex;
+    /**
+     * Returns the explicit transaction/database scope, without resolving model or app defaults.
+     * Infrastructure adapters use this to participate in an application's atomic outbox writes.
+     * @returns Current scoped connection, or undefined outside withDb().
+     */
+    static getScopedDb(): Knex | undefined;
     /**
      * Runs work with a temporary database connection for all ActiveRecord statics.
      */

package/dist/db/ActiveRecord.js

@@ -132,6 +132,14 @@ export class ActiveRecord {
             ?? activeAppDatabase()
             ?? defaultDb();
     }
+    /**
+     * Returns the explicit transaction/database scope, without resolving model or app defaults.
+     * Infrastructure adapters use this to participate in an application's atomic outbox writes.
+     * @returns Current scoped connection, or undefined outside withDb().
+     */
+    static getScopedDb() {
+        return scopedDb.getStore();
+    }
     /**
      * Runs work with a temporary database connection for all ActiveRecord statics.
      */

package/dist/db/connection.js

@@ -1,5 +1,6 @@
 import 'dotenv/config';
 import knex from 'knex';
+import { utcDate } from '@db3.ai/pure/dates';
 import { rememberDatabaseDialect, resolveDatabaseDialect, } from './dialects/index.js';
 let database = null;
 /**
@@ -16,9 +17,14 @@ function requiredEnv(name) {
  * Builds a Knex connection value from the current process environment.
  */
 function databaseConnection(dialect) {
-    if (process.env.DATABASE_URL)
-        return process.env.DATABASE_URL;
+    if (process.env.DATABASE_URL) {
+        const url = new URL(process.env.DATABASE_URL);
+        if (dialect.name !== 'postgres')
+            url.searchParams.set('timezone', 'Z');
+        return url.toString();
+    }
     return {
+        ...(dialect.name !== 'postgres' ? { timezone: 'Z' } : {}),
         host: process.env.DB_HOST || '127.0.0.1',
         port: Number(process.env.DB_PORT || dialect.defaultPort),
         user: process.env.DB_USER || 'root',
@@ -36,6 +42,12 @@ export function db() {
             client: dialect.knexClient,
             connection: databaseConnection(dialect),
             pool: {
+                /** Initializes SQL functions and TIMESTAMP conversion in UTC on every pooled connection. */
+                afterCreate(connection, done) {
+                    if (dialect.name === 'postgres')
+                        connection.setTypeParser?.(1114, utcDate);
+                    connection.query(dialect.name === 'postgres' ? "SET TIME ZONE 'UTC'" : "SET time_zone = '+00:00'", error => done(error, connection));
+                },
                 min: Number(process.env.DB_POOL_MIN || 0),
                 max: Number(process.env.DB_POOL_MAX || 10),
             },

package/dist/db/fields/TimestampField.d.ts

@@ -28,7 +28,7 @@ export declare class TimestampField extends FieldType<Date | null, Date | string
     /**
      * Converts app-memory Date to database value.
      */
-    protected toDbValue(input: Date | null): Date | null;
+    protected toDbValue(input: Date | null): Date | string | null;
     protected defaultFormComponent(): string;
     protected defaultSearchFilterComponent(): string | null;
     /**

package/dist/db/fields/TimestampField.js

@@ -1,3 +1,4 @@
+import { utcDate } from '@db3.ai/pure/dates';
 import { FieldType, fieldSchemaIndexes, } from '../FieldType.js';
 /**
  * Timestamp field using `Date | null` in app memory.
@@ -16,17 +17,7 @@ export class TimestampField extends FieldType {
      * Parses app input into a Date object.
      */
     parse(input) {
-        if (input === null || input === undefined || input === '') {
-            return null;
-        }
-        if (input instanceof Date) {
-            return input;
-        }
-        const date = new Date(String(input));
-        if (Number.isNaN(date.getTime())) {
-            return null;
-        }
-        return date;
+        return input instanceof Date || typeof input === 'string' ? utcDate(input) : null;
     }
     /**
      * Converts database value into app-memory Date.
@@ -41,7 +32,11 @@ export class TimestampField extends FieldType {
         if (input === null || input === undefined) {
             return null;
         }
-        return input;
+        // PostgreSQL timestamp-without-timezone ignores offsets on Date parameters.
+        // Send UTC calendar components explicitly rather than the driver's local rendering.
+        return this.schemaDialect().name === 'postgres'
+            ? input.toISOString().replace('T', ' ').replace('Z', '')
+            : input;
     }
     defaultFormComponent() {
         return 'DomDatePicker';

package/dist/db/migrations/DatabaseMigrationManager.d.ts

@@ -1,4 +1,4 @@
-import type { DatabaseCheckResult, DatabaseMigrationManagerOptions, DatabaseMigrationStatus, DatabaseSyncResult, MakeMigrationOptions, MakeMigrationResult, MigrateOptions, MigrateResult } from './contracts/index.js';
+import type { DatabaseCheckResult, DatabaseMigrationManagerOptions, DatabaseMigrationStatus, DatabaseSyncResult, MakeMigrationOptions, MakeMigrationResult, MigrateOptions, MigrateResult, RollbackResult } from './contracts/index.js';
 /**
  * Reusable application-configured model migration service.
  *
@@ -44,6 +44,8 @@ export declare class DatabaseMigrationManager {
      * @returns Applied migration names, batch, and optional baselined filenames.
      */
     migrate(options?: MigrateOptions): Promise<MigrateResult>;
+    /** Runs the latest committed migration's own down function. The caller must quiesce consumers first. */
+    rollback(): Promise<RollbackResult>;
     /**
      * Runs the development convenience flow under one generation lock.
      *

package/dist/db/migrations/DatabaseMigrationManager.js

@@ -2,7 +2,7 @@ import { access, mkdir, open, readdir, readFile, rename, unlink, writeFile, } fr
 import { basename, dirname, extname, isAbsolute, join, } from 'node:path';
 import { inspectDatabaseSchema } from './DatabaseSchemaInspector.js';
 import { DatabaseMigrationBaselineError, DatabaseMigrationLockError, DatabaseMigrationSourceGenerationError, } from './errors.js';
-import { renderKnexMigration } from './KnexMigrationRenderer.js';
+import { renderKnexMigration } from './renderKnexMigration.js';
 import { collectModelSchema } from './ModelSchemaCollector.js';
 import { diffSchemaSnapshots } from './SchemaDiffer.js';
 import { promoteDestructiveSchemaChanges } from './promoteDestructiveSchemaChanges.js';
@@ -35,6 +35,7 @@ export class DatabaseMigrationManager {
             ...options,
             models: [...options.models],
             migrationTableName: options.migrationTableName ?? DEFAULT_MIGRATION_TABLE,
+            migrationExtension: options.migrationExtension ?? '.ts',
             loadExtensions: options.loadExtensions ?? DEFAULT_LOAD_EXTENSIONS,
             environment: options.environment ?? process.env.NODE_ENV ?? 'development',
             generationLockFile,
@@ -128,6 +129,11 @@ export class DatabaseMigrationManager {
             baselined,
         };
     }
+    /** Runs the latest committed migration's own down function. The caller must quiesce consumers first. */
+    async rollback() {
+        const [batch, names] = await this.#options.db.migrate.down(this.#knexConfig());
+        return { reverted: names.map(String), batch: typeof batch === 'number' ? batch : null };
+    }
     /**
      * Runs the development convenience flow under one generation lock.
      *
@@ -187,8 +193,8 @@ export class DatabaseMigrationManager {
             };
         }
         const name = migrationName(options.name, plan);
-        const file = join(this.#options.migrationsDirectory, `${formatMigrationTimestamp(this.#options.now())}_${name}.ts`);
-        const source = renderKnexMigration(plan);
+        const file = join(this.#options.migrationsDirectory, `${formatMigrationTimestamp(this.#options.now())}_${name}${this.#options.migrationExtension}`);
+        const source = renderKnexMigration(plan, this.#options.migrationExtension === '.mjs' ? 'javascript' : 'typescript');
         await writeMigrationAndSnapshotAtomically(file, source, this.#options.snapshotFile, desired);
         return {
             generated: true,

package/dist/db/migrations/contracts/DatabaseMigration.d.ts

@@ -22,6 +22,8 @@ export interface DatabaseMigrationManagerOptions {
     migrationSchemaName?: string;
     /** Migration file extensions Knex may load. */
     loadExtensions?: readonly string[];
+    /** Generated migration format. Use .mjs for assets shared unchanged with npm packages. */
+    migrationExtension?: '.ts' | '.mjs';
     /** Current application environment. Source generation is refused in production. */
     environment?: string;
     /** Absolute cross-process lock path used while generating source files. */
@@ -116,3 +118,8 @@ export interface DatabaseSyncResult {
     migrate: MigrateResult | null;
     check: DatabaseCheckResult | null;
 }
+/** Result of executing the latest migration's app-authored down function. */
+export interface RollbackResult {
+    reverted: string[];
+    batch: number | null;
+}

package/dist/db/migrations/index.d.ts

@@ -2,7 +2,7 @@ export * from './contracts/index.js';
 export * from './DatabaseMigrationManager.js';
 export * from './DatabaseSchemaInspector.js';
 export * from './errors.js';
-export * from './KnexMigrationRenderer.js';
+export * from './renderKnexMigration.js';
 export * from './ModelSchemaCollector.js';
 export * from './promoteDestructiveSchemaChanges.js';
 export * from './SchemaDiffer.js';