@c9up/ream 0.2.8 → 0.2.9

package/dist/commands/ScheduleRun.js

@@ -0,0 +1,61 @@
+/**
+ * `schedule:run <name>` — run one registered task immediately.
+ *
+ * An admin override: it calls the task body directly, so it bypasses both the
+ * cron schedule and the distributed lock. That is the point — you reach for it
+ * when a task must run now, or to see it fail with your own eyes — and it is
+ * also why the exit codes are distinct: `1` the task failed, `2` no such task,
+ * `3` an invocation of it is already in flight.
+ */
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+import { BaseCommand } from '../console/BaseCommand.js';
+import { args } from '../console/decorators.js';
+import { resolveScheduler } from './scheduler_resolver.js';
+export default class ScheduleRun extends BaseCommand {
+    static commandName = 'schedule:run';
+    static description = 'Run a registered scheduled task once, now (bypasses the lock)';
+    static options = { startApp: true };
+    async run() {
+        // Rejected here rather than in the scheduler so the message arrives without
+        // the operator first paying for a boot.
+        if (this.name.trim() === '') {
+            this.logger.error('Task name cannot be empty. Usage: schedule:run <name>');
+            this.exitCode = 1;
+            return;
+        }
+        const scheduler = await resolveScheduler(this);
+        if (!scheduler)
+            return;
+        const result = await scheduler.runTaskNow(this.name);
+        const duration = Math.round(result.durationMs);
+        if (result.outcome === 'unknown') {
+            this.logger.error(`Unknown task: ${this.name}. Run "schedule:list" to see the registered tasks.`);
+            this.exitCode = 2;
+            return;
+        }
+        if (result.outcome === 'already-running') {
+            this.logger.error(`Task ${this.name} is already running in this process — skipped. Try again once it completes.`);
+            this.exitCode = 3;
+            return;
+        }
+        if (result.outcome === 'completed') {
+            this.logger.success(`${this.name} completed in ${duration} ms`);
+            return;
+        }
+        this.logger.error(`${this.name} failed after ${duration} ms: ${result.error?.message || 'unknown error'}`);
+        this.exitCode = 1;
+    }
+}
+__decorate([
+    args.string({ description: 'Task name, as `schedule:list` prints it' }),
+    __metadata("design:type", String)
+], ScheduleRun.prototype, "name", void 0);
+//# sourceMappingURL=ScheduleRun.js.map

package/dist/commands/ScheduleRun.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ScheduleRun.js","sourceRoot":"","sources":["../../src/commands/ScheduleRun.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;;;;;;;;;;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAA;AACvD,OAAO,EAAE,IAAI,EAAE,MAAM,0BAA0B,CAAA;AAE/C,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAA;AAE1D,MAAM,CAAC,OAAO,OAAO,WAAY,SAAQ,WAAW;IAClD,MAAM,CAAU,WAAW,GAAG,cAAc,CAAA;IAC5C,MAAM,CAAU,WAAW,GAAG,+DAA+D,CAAA;IAC7F,MAAM,CAAU,OAAO,GAAmB,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAA;IAK5D,KAAK,CAAC,GAAG;QACP,4EAA4E;QAC5E,wCAAwC;QACxC,IAAI,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;YAC5B,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,uDAAuD,CAAC,CAAA;YAC1E,IAAI,CAAC,QAAQ,GAAG,CAAC,CAAA;YACjB,OAAM;QACR,CAAC;QAED,MAAM,SAAS,GAAG,MAAM,gBAAgB,CAAC,IAAI,CAAC,CAAA;QAC9C,IAAI,CAAC,SAAS;YAAE,OAAM;QAEtB,MAAM,MAAM,GAAG,MAAM,SAAS,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;QACpD,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,UAAU,CAAC,CAAA;QAE9C,IAAI,MAAM,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;YACjC,IAAI,CAAC,MAAM,CAAC,KAAK,CACf,iBAAiB,IAAI,CAAC,IAAI,oDAAoD,CAC/E,CAAA;YACD,IAAI,CAAC,QAAQ,GAAG,CAAC,CAAA;YACjB,OAAM;QACR,CAAC;QAED,IAAI,MAAM,CAAC,OAAO,KAAK,iBAAiB,EAAE,CAAC;YACzC,IAAI,CAAC,MAAM,CAAC,KAAK,CACf,QAAQ,IAAI,CAAC,IAAI,6EAA6E,CAC/F,CAAA;YACD,IAAI,CAAC,QAAQ,GAAG,CAAC,CAAA;YACjB,OAAM;QACR,CAAC;QAED,IAAI,MAAM,CAAC,OAAO,KAAK,WAAW,EAAE,CAAC;YACnC,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,GAAG,IAAI,CAAC,IAAI,iBAAiB,QAAQ,KAAK,CAAC,CAAA;YAC/D,OAAM;QACR,CAAC;QAED,IAAI,CAAC,MAAM,CAAC,KAAK,CACf,GAAG,IAAI,CAAC,IAAI,iBAAiB,QAAQ,QAAQ,MAAM,CAAC,KAAK,EAAE,OAAO,IAAI,eAAe,EAAE,CACxF,CAAA;QACD,IAAI,CAAC,QAAQ,GAAG,CAAC,CAAA;IACnB,CAAC;;AA1CO;IADP,IAAI,CAAC,MAAM,CAAC,EAAE,WAAW,EAAE,yCAAyC,EAAE,CAAC;;yCACpD"}

package/dist/commands/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * `@c9up/ream/commands` — the commands the framework itself ships.
+ *
+ * The shape AdonisJS uses for `@adonisjs/core/commands`: a module answering
+ * `getMetaData()` then `getCommand()`, so listing a command does not import it.
+ *
+ * The kernel registers this loader on its own rather than waiting for an entry
+ * in `reamrc.commands` — the deviation from AdonisJS, where the starter kit
+ * lists it. These commands were part of the `ream` binary before they were
+ * classes, and an application that upgrades must not silently lose them.
+ */
+import type { CommandClass, SerializedCommand } from '../console/types.js';
+export declare function getMetaData(): Promise<SerializedCommand[]>;
+export declare function getCommand(metadata: SerializedCommand): Promise<CommandClass | null>;
+//# sourceMappingURL=index.d.ts.map

package/dist/commands/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/commands/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAA;AA4C1E,wBAAsB,WAAW,IAAI,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAUhE;AAED,wBAAsB,UAAU,CAAC,QAAQ,EAAE,iBAAiB,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CAI1F"}

package/dist/commands/index.js

@@ -0,0 +1,63 @@
+/**
+ * `@c9up/ream/commands` — the commands the framework itself ships.
+ *
+ * The shape AdonisJS uses for `@adonisjs/core/commands`: a module answering
+ * `getMetaData()` then `getCommand()`, so listing a command does not import it.
+ *
+ * The kernel registers this loader on its own rather than waiting for an entry
+ * in `reamrc.commands` — the deviation from AdonisJS, where the starter kit
+ * lists it. These commands were part of the `ream` binary before they were
+ * classes, and an application that upgrades must not silently lose them.
+ */
+const COMMANDS = [
+    // The registry commands first: a data package registers its runner, and
+    // these drive whatever registered — they name no store.
+    {
+        commandName: 'migrate',
+        description: 'Run pending migrations for every registered migration source',
+        load: () => import('./Migrate.js'),
+    },
+    {
+        commandName: 'migrate:rollback',
+        description: 'Roll back the last batch for every registered migration source',
+        load: () => import('./MigrateRollback.js'),
+    },
+    {
+        commandName: 'migrate:status',
+        description: 'Show applied and pending migrations for every source',
+        load: () => import('./MigrateStatus.js'),
+    },
+    {
+        commandName: 'schedule:list',
+        description: 'List every registered scheduled task, its next run and its stats',
+        load: () => import('./ScheduleList.js'),
+    },
+    {
+        commandName: 'schedule:run',
+        description: 'Run a registered scheduled task once, now (bypasses the lock)',
+        load: () => import('./ScheduleRun.js'),
+    },
+];
+/** `migrate:status` → `migrate`; a name without a colon has no namespace. */
+function namespaceOf(commandName) {
+    const colon = commandName.indexOf(':');
+    return colon === -1 ? null : commandName.slice(0, colon);
+}
+export async function getMetaData() {
+    return COMMANDS.map((entry) => ({
+        commandName: entry.commandName,
+        namespace: namespaceOf(entry.commandName),
+        description: entry.description,
+        aliases: [],
+        options: { startApp: true },
+        args: [],
+        flags: [],
+    }));
+}
+export async function getCommand(metadata) {
+    const entry = COMMANDS.find((command) => command.commandName === metadata.commandName);
+    if (!entry)
+        return null;
+    return (await entry.load()).default;
+}
+//# sourceMappingURL=index.js.map

package/dist/commands/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/commands/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAUH,MAAM,QAAQ,GAAqB;IACjC,wEAAwE;IACxE,wDAAwD;IACxD;QACE,WAAW,EAAE,SAAS;QACtB,WAAW,EAAE,8DAA8D;QAC3E,IAAI,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,cAAc,CAAC;KACnC;IACD;QACE,WAAW,EAAE,kBAAkB;QAC/B,WAAW,EAAE,gEAAgE;QAC7E,IAAI,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,sBAAsB,CAAC;KAC3C;IACD;QACE,WAAW,EAAE,gBAAgB;QAC7B,WAAW,EAAE,sDAAsD;QACnE,IAAI,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,oBAAoB,CAAC;KACzC;IACD;QACE,WAAW,EAAE,eAAe;QAC5B,WAAW,EAAE,kEAAkE;QAC/E,IAAI,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,mBAAmB,CAAC;KACxC;IACD;QACE,WAAW,EAAE,cAAc;QAC3B,WAAW,EAAE,+DAA+D;QAC5E,IAAI,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,kBAAkB,CAAC;KACvC;CACF,CAAA;AAED,6EAA6E;AAC7E,SAAS,WAAW,CAAC,WAAmB;IACtC,MAAM,KAAK,GAAG,WAAW,CAAC,OAAO,CAAC,GAAG,CAAC,CAAA;IACtC,OAAO,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAA;AAC1D,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,WAAW;IAC/B,OAAO,QAAQ,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;QAC9B,WAAW,EAAE,KAAK,CAAC,WAAW;QAC9B,SAAS,EAAE,WAAW,CAAC,KAAK,CAAC,WAAW,CAAC;QACzC,WAAW,EAAE,KAAK,CAAC,WAAW;QAC9B,OAAO,EAAE,EAAE;QACX,OAAO,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE;QAC3B,IAAI,EAAE,EAAE;QACR,KAAK,EAAE,EAAE;KACV,CAAC,CAAC,CAAA;AACL,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,QAA2B;IAC1D,MAAM,KAAK,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,WAAW,KAAK,QAAQ,CAAC,WAAW,CAAC,CAAA;IACtF,IAAI,CAAC,KAAK;QAAE,OAAO,IAAI,CAAA;IACvB,OAAO,CAAC,MAAM,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,OAAO,CAAA;AACrC,CAAC"}

package/dist/commands/scheduler_resolver.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Resolve the scheduler for the `schedule:*` commands.
+ *
+ * Shared because the failure is the same one on both, and it is a
+ * configuration mistake rather than a crash: the provider is simply not in the
+ * list, and the message has to say so — a container error mentioning an
+ * unbound `scheduler` binding tells an operator nothing.
+ */
+import type { BaseCommand } from '../console/BaseCommand.js';
+import type { Scheduler } from '../scheduler/Scheduler.js';
+export declare function resolveScheduler(command: BaseCommand): Promise<Scheduler | undefined>;
+//# sourceMappingURL=scheduler_resolver.d.ts.map

package/dist/commands/scheduler_resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scheduler_resolver.d.ts","sourceRoot":"","sources":["../../src/commands/scheduler_resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAA;AAC5D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAA;AAE1D,wBAAsB,gBAAgB,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,SAAS,GAAG,SAAS,CAAC,CAU3F"}

package/dist/commands/scheduler_resolver.js

@@ -0,0 +1,19 @@
+/**
+ * Resolve the scheduler for the `schedule:*` commands.
+ *
+ * Shared because the failure is the same one on both, and it is a
+ * configuration mistake rather than a crash: the provider is simply not in the
+ * list, and the message has to say so — a container error mentioning an
+ * unbound `scheduler` binding tells an operator nothing.
+ */
+export async function resolveScheduler(command) {
+    try {
+        return await command.app.container.resolve('scheduler');
+    }
+    catch {
+        command.logger.error('No ScheduleProvider is registered. Add ScheduleProvider to the providers list in reamrc.ts.');
+        command.exitCode = 2;
+        return undefined;
+    }
+}
+//# sourceMappingURL=scheduler_resolver.js.map

package/dist/commands/scheduler_resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scheduler_resolver.js","sourceRoot":"","sources":["../../src/commands/scheduler_resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,OAAoB;IACzD,IAAI,CAAC;QACH,OAAO,MAAM,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,OAAO,CAAY,WAAW,CAAC,CAAA;IACpE,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,6FAA6F,CAC9F,CAAA;QACD,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAA;QACpB,OAAO,SAAS,CAAA;IAClB,CAAC;AACH,CAAC"}

package/dist/index.d.ts

@@ -119,5 +119,5 @@ export { BaseEvent, Emitter, type EmitterResolver, type ListenerClass, } from '.
 export { type BufferedEvent, type BufferedEventName, type EventFinder, EventsBuffer, } from './events/EventsBuffer.js';
 export type { ErrorReporter, LockBackend, RunTaskOutcome, ScheduleEvent, ScheduleEventSink, ScheduleInvocation, ScheduleMetadata, ScheduleProviderOptions, SchedulerOptions, ScheduleTaskCompletedEvent, ScheduleTaskFailedEvent, ScheduleTaskSkippedEvent, ScheduleTaskStartedEvent, TaskInfo, TaskStats, } from './scheduler/index.js';
 export { getScheduleMetadata, MemoryLockBackend, SCHEDULE_METADATA_KEY, Schedule, ScheduleProvider, Scheduler, StatsTracker, } from './scheduler/index.js';
-export declare const VERSION = "0.2.8";
+export declare const VERSION = "0.2.9";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -91,5 +91,5 @@ export { defineConfig as defineEventsConfig } from './events/config.js';
 export { BaseEvent, Emitter, } from './events/Emitter.js';
 export { EventsBuffer, } from './events/EventsBuffer.js';
 export { getScheduleMetadata, MemoryLockBackend, SCHEDULE_METADATA_KEY, Schedule, ScheduleProvider, Scheduler, StatsTracker, } from './scheduler/index.js';
-export const VERSION = '0.2.8';
+export const VERSION = '0.2.9';
 //# sourceMappingURL=index.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@c9up/ream",
-  "version": "0.2.8",
+  "version": "0.2.9",
   "description": "Ream — Rust-powered Node.js application framework",
   "license": "MIT",
   "type": "module",
@@ -19,6 +19,10 @@
       "types": "./dist/http/Exception.d.ts",
       "import": "./dist/http/Exception.js"
     },
+    "./commands": {
+      "types": "./dist/commands/index.d.ts",
+      "import": "./dist/commands/index.js"
+    },
     "./console": {
       "types": "./dist/console/index.d.ts",
       "import": "./dist/console/index.js"

package/src/Ignitor.ts

@@ -1137,6 +1137,7 @@ export class ConsoleKernel {
 
     return {
       getMetaData: async () => {
+        await this.#loadFrameworkCommands(found)
         await this.#discoverAppCommands(kernel, found)
         await this.#loadPackageCommands(found)
         // Imported here, not at the top of the file: the console stack is only
@@ -1149,6 +1150,24 @@ export class ConsoleKernel {
     }
   }
 
+  /**
+   * Register the framework's own commands (`@c9up/ream/commands`).
+   *
+   * AdonisJS lists its equivalent in the rc file, which its starter kit writes.
+   * Ream registers them here instead, and first: these were subcommands of the
+   * `ream` binary before they were classes, so an application that upgrades
+   * would otherwise lose them without ever having asked for them. Loading them
+   * first also means an application that ships a command of the same name wins
+   * — the later registration replaces this one.
+   */
+  async #loadFrameworkCommands(found: Map<string, CommandClass>): Promise<void> {
+    const loader = await import('./commands/index.js')
+    for (const metadata of await loader.getMetaData()) {
+      const command = await loader.getCommand(metadata)
+      if (command !== null) found.set(command.commandName, command)
+    }
+  }
+
   /**
    * Load every command in the app's `commands/` directory.
    *
@@ -1200,13 +1219,30 @@ export class ConsoleKernel {
     if (!declared) return
 
     for (const entry of declared) {
-      const command = commandOf(await entry())
+      const module = await entry()
+
+      // A package with several commands ships ONE loader — `getMetaData()` +
+      // `getCommand()` — so its rc entry is one line and `ream list` reads
+      // metadata without importing a single command class. That is what makes
+      // this channel usable for a package that has six of them, and why
+      // requiring a default export per command pushed packages to wire
+      // themselves into the CLI binary instead.
+      const loader = loaderOf(module)
+      if (loader) {
+        for (const metadata of await loader.getMetaData()) {
+          const loaded = await loader.getCommand(metadata)
+          if (loaded !== null) found.set(loaded.commandName, loaded)
+        }
+        continue
+      }
+
+      const command = commandOf(module)
       if (command === undefined) {
         throw new ReamError(
           'E_CONSOLE_INVALID_COMMAND',
-          'An entry of reamrc.ts `commands` does not default-export a command class.',
+          'An entry of reamrc.ts `commands` is neither a command loader nor a default-exported command class.',
           {
-            hint: 'Expected `export default class X { static commandName = "..."; static description = "..."; run() {} }`.',
+            hint: 'Ship `export function getMetaData()` + `export function getCommand(metadata)` for a package with several commands, or `export default class X { static commandName = "..."; static description = "..."; run() {} }` for one.',
           },
         )
       }
@@ -1246,6 +1282,18 @@ interface ConsoleCommandKernel {
 }
 
 /** The command a module default-exports, or undefined when it exports none. */
+/**
+ * A module that enumerates its own commands — the shape AdonisJS packages ship
+ * and the one `CommandLoader` already describes.
+ */
+function loaderOf(mod: unknown): CommandLoader | undefined {
+  if (typeof mod !== 'object' || mod === null) return undefined
+  const getMetaData = Reflect.get(mod, 'getMetaData')
+  const getCommand = Reflect.get(mod, 'getCommand')
+  if (typeof getMetaData !== 'function' || typeof getCommand !== 'function') return undefined
+  return mod as CommandLoader
+}
+
 function commandOf(mod: unknown): CommandClass | undefined {
   if (typeof mod !== 'object' || mod === null) return undefined
   const value = Reflect.get(mod, 'default')

package/src/commands/Migrate.ts

@@ -0,0 +1,18 @@
+/** `migrate` — apply every pending migration, in every registered store. */
+
+import type { RegisteredMigrationSource } from '../migrations/types.js'
+import { MigrateBase } from './MigrateBase.js'
+
+export default class Migrate extends MigrateBase {
+  static override commandName = 'migrate'
+  static override description = 'Run pending migrations for every registered migration source'
+
+  protected async migrateSource(source: RegisteredMigrationSource): Promise<void> {
+    const executed = await source.runner.migrate()
+    if (executed.length === 0) {
+      this.report(source, 'nothing to migrate.')
+      return
+    }
+    for (const name of executed) this.report(source, `migrated: ${name}`)
+  }
+}

package/src/commands/MigrateBase.ts

@@ -0,0 +1,81 @@
+/**
+ * What `migrate`, `migrate:rollback` and `migrate:status` share.
+ *
+ * All three drive the SAME thing — the `migrations` registry, where each data
+ * package puts its runner — and differ only in which method they call and how
+ * they print the result. A ream particularity, deliberate: AdonisJS has one
+ * store and can name it, while an application here may hold a relational store
+ * and a time-series one at once, so the command names none of them.
+ *
+ * Sequentially, never in parallel: two stores on one database server would
+ * contend on locks, and interleaved output makes a failure impossible to
+ * attribute to the store that caused it.
+ */
+
+import { BaseCommand } from '../console/BaseCommand.js'
+import { flags } from '../console/decorators.js'
+import type { CommandOptions } from '../console/types.js'
+import type { MigrationRegistry } from '../migrations/MigrationRegistry.js'
+import type { RegisteredMigrationSource } from '../migrations/types.js'
+
+export abstract class MigrateBase extends BaseCommand {
+  static override options: CommandOptions = { startApp: true }
+
+  @flags.string({
+    description: 'Only this migration source, by the name its package registered',
+  })
+  declare only?: string
+
+  /** What to do with one store. Implemented by each command. */
+  protected abstract migrateSource(source: RegisteredMigrationSource): Promise<void>
+
+  async run(): Promise<void> {
+    const sources = await this.#resolveSources()
+    if (sources === undefined) return
+
+    for (const source of sources) {
+      await this.migrateSource(source)
+    }
+  }
+
+  /** The line every message is prefixed with, so multi-store output stays legible. */
+  protected report(source: RegisteredMigrationSource, message: string): void {
+    this.logger.log(`  [${source.name}] ${message}`)
+  }
+
+  /**
+   * The sources this run covers, or `undefined` when the run should stop —
+   * having said why.
+   *
+   * An empty registry is NOT a failure: an application may legitimately have no
+   * data package yet. Naming which thing is missing beats exiting non-zero on a
+   * state the user may have chosen.
+   */
+  async #resolveSources(): Promise<RegisteredMigrationSource[] | undefined> {
+    const registry = await this.app.container.resolve<MigrationRegistry>('migrations')
+
+    if (this.only !== undefined) {
+      const picked = registry.get(this.only)
+      if (picked === undefined) {
+        const names = registry.names()
+        this.logger.error(`No migration source named "${this.only}".`)
+        this.logger.error(
+          names.length > 0
+            ? `  Registered: ${names.join(', ')}`
+            : '  No data package registered one. Is its provider in reamrc.ts?',
+        )
+        this.exitCode = 1
+        return undefined
+      }
+      return [picked]
+    }
+
+    const sources = registry.all()
+    if (sources.length === 0) {
+      this.logger.info('No migration source registered.')
+      this.logger.info('  A data package registers one from its provider — check reamrc.ts.')
+      return undefined
+    }
+    return sources
+  }
+}

package/src/commands/MigrateRollback.ts

@@ -0,0 +1,18 @@
+/** `migrate:rollback` — undo the last batch, in every registered store. */
+
+import type { RegisteredMigrationSource } from '../migrations/types.js'
+import { MigrateBase } from './MigrateBase.js'
+
+export default class MigrateRollback extends MigrateBase {
+  static override commandName = 'migrate:rollback'
+  static override description = 'Roll back the last batch for every registered migration source'
+
+  protected async migrateSource(source: RegisteredMigrationSource): Promise<void> {
+    const rolled = await source.runner.rollback()
+    if (rolled.length === 0) {
+      this.report(source, 'nothing to rollback.')
+      return
+    }
+    for (const name of rolled) this.report(source, `rolled back: ${name}`)
+  }
+}

package/src/commands/MigrateStatus.ts

@@ -0,0 +1,22 @@
+/** `migrate:status` — what has run and what has not, in every registered store. */
+
+import type { RegisteredMigrationSource } from '../migrations/types.js'
+import { MigrateBase } from './MigrateBase.js'
+
+export default class MigrateStatus extends MigrateBase {
+  static override commandName = 'migrate:status'
+  static override description = 'Show applied and pending migrations for every source'
+
+  protected async migrateSource(source: RegisteredMigrationSource): Promise<void> {
+    const statuses = await source.runner.status()
+    if (statuses.length === 0) {
+      this.report(source, 'no migrations found.')
+      return
+    }
+    for (const node of statuses) {
+      const mark = node.status === 'applied' ? '✓' : '○'
+      const batch = node.batch === undefined ? '' : ` (batch ${node.batch})`
+      this.report(source, `${mark} ${node.name}${batch}`)
+    }
+  }
+}

package/src/commands/ScheduleList.ts

@@ -0,0 +1,66 @@
+/**
+ * `schedule:list` — every registered task, when it next fires, and how its past
+ * runs went.
+ *
+ * The columns are the operator's questions in order: is my task registered at
+ * all, on what schedule, when does it fire next, when did it last fire, and is
+ * it failing. Stats come from the scheduler's own tracker, so a task that has
+ * never run reads as `—` rather than a zero that looks like a result.
+ */
+
+import { BaseCommand } from '../console/BaseCommand.js'
+import type { CommandOptions } from '../console/types.js'
+import { resolveScheduler } from './scheduler_resolver.js'
+
+/** Over-long names and cron expressions are truncated so the table stays a table. */
+function truncate(value: string, width: number): string {
+  return value.length > width ? `${value.slice(0, width - 1)}…` : value
+}
+
+function asDate(ms: number | null): string {
+  return ms === null ? '—' : new Date(ms).toISOString()
+}
+
+export default class ScheduleList extends BaseCommand {
+  static override commandName = 'schedule:list'
+  static override description = 'List every registered scheduled task, its next run and its stats'
+  static override options: CommandOptions = { startApp: true }
+
+  async run(): Promise<void> {
+    const scheduler = await resolveScheduler(this)
+    if (!scheduler) return
+
+    const tasks = scheduler.listTasks()
+    if (tasks.length === 0) {
+      this.logger.info('No scheduled tasks registered.')
+      return
+    }
+
+    this.logger.log(
+      [
+        'NAME'.padEnd(32),
+        'CRON'.padEnd(18),
+        'NEXT RUN'.padEnd(22),
+        'LAST RUN'.padEnd(22),
+        'RUNS'.padStart(6),
+        'ERR'.padStart(5),
+        'AVG(ms)'.padStart(9),
+      ].join(' '),
+    )
+
+    for (const task of tasks) {
+      const stats = scheduler.getStats(task.name)
+      this.logger.log(
+        [
+          truncate(task.name, 32).padEnd(32),
+          truncate(task.cronExpr, 18).padEnd(18),
+          asDate(task.nextRun).padEnd(22),
+          asDate(stats.lastRunMs).padEnd(22),
+          String(stats.runCount).padStart(6),
+          String(stats.errorCount).padStart(5),
+          String(Math.round(stats.avgDurationMs)).padStart(9),
+        ].join(' '),
+      )
+    }
+  }
+}

package/src/commands/ScheduleRun.ts

@@ -0,0 +1,65 @@
+/**
+ * `schedule:run <name>` — run one registered task immediately.
+ *
+ * An admin override: it calls the task body directly, so it bypasses both the
+ * cron schedule and the distributed lock. That is the point — you reach for it
+ * when a task must run now, or to see it fail with your own eyes — and it is
+ * also why the exit codes are distinct: `1` the task failed, `2` no such task,
+ * `3` an invocation of it is already in flight.
+ */
+
+import { BaseCommand } from '../console/BaseCommand.js'
+import { args } from '../console/decorators.js'
+import type { CommandOptions } from '../console/types.js'
+import { resolveScheduler } from './scheduler_resolver.js'
+
+export default class ScheduleRun extends BaseCommand {
+  static override commandName = 'schedule:run'
+  static override description = 'Run a registered scheduled task once, now (bypasses the lock)'
+  static override options: CommandOptions = { startApp: true }
+
+  @args.string({ description: 'Task name, as `schedule:list` prints it' })
+  declare name: string
+
+  async run(): Promise<void> {
+    // Rejected here rather than in the scheduler so the message arrives without
+    // the operator first paying for a boot.
+    if (this.name.trim() === '') {
+      this.logger.error('Task name cannot be empty. Usage: schedule:run <name>')
+      this.exitCode = 1
+      return
+    }
+
+    const scheduler = await resolveScheduler(this)
+    if (!scheduler) return
+
+    const result = await scheduler.runTaskNow(this.name)
+    const duration = Math.round(result.durationMs)
+
+    if (result.outcome === 'unknown') {
+      this.logger.error(
+        `Unknown task: ${this.name}. Run "schedule:list" to see the registered tasks.`,
+      )
+      this.exitCode = 2
+      return
+    }
+
+    if (result.outcome === 'already-running') {
+      this.logger.error(
+        `Task ${this.name} is already running in this process — skipped. Try again once it completes.`,
+      )
+      this.exitCode = 3
+      return
+    }
+
+    if (result.outcome === 'completed') {
+      this.logger.success(`${this.name} completed in ${duration} ms`)
+      return
+    }
+
+    this.logger.error(
+      `${this.name} failed after ${duration} ms: ${result.error?.message || 'unknown error'}`,
+    )
+    this.exitCode = 1
+  }
+}