@strav/cli 0.4.17 → 0.4.25

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@strav/cli",
-  "version": "0.4.17",
+  "version": "0.4.25",
   "type": "module",
   "description": "CLI framework and code generators for the Strav framework",
   "license": "MIT",
@@ -34,11 +34,11 @@
     "strav": "./src/cli/strav.ts"
   },
   "peerDependencies": {
-    "@strav/kernel": "0.4.17",
-    "@strav/http": "0.4.17",
-    "@strav/database": "0.4.17",
-    "@strav/queue": "0.4.17",
-    "@strav/signal": "0.4.17"
+    "@strav/kernel": "0.4.25",
+    "@strav/http": "0.4.25",
+    "@strav/database": "0.4.25",
+    "@strav/queue": "0.4.25",
+    "@strav/signal": "0.4.25"
   },
   "dependencies": {
     "chalk": "^5.6.2",

package/src/cli/bootstrap.ts

@@ -41,12 +41,23 @@ export async function shutdown(db: Database): Promise<void> {
   await db.close()
 }
 
+export interface WithProvidersOptions {
+  /**
+   * Install SIGINT/SIGTERM handlers for graceful shutdown. Default: `true`.
+   * Set to `false` when the caller owns signal handling and must control
+   * shutdown ordering — e.g. `queue:work`, which lets the worker drain its
+   * in-flight job before `app.shutdown()` tears down providers.
+   */
+  signalHandlers?: boolean
+}
+
 /**
  * Bootstrap an Application with the given service providers.
  *
  * Creates a fresh Application, registers all providers, boots them
  * in dependency order, and returns the running application.
- * Signal handlers for graceful shutdown are installed automatically.
+ * Signal handlers for graceful shutdown are installed automatically
+ * unless `options.signalHandlers` is `false`.
  *
  * @example
  * const app = await withProviders([
@@ -55,9 +66,12 @@ export async function shutdown(db: Database): Promise<void> {
  *   new AuthProvider({ resolver: (id) => User.find(id) }),
  * ])
  */
-export async function withProviders(providers: ServiceProvider[]): Promise<Application> {
+export async function withProviders(
+  providers: ServiceProvider[],
+  options?: WithProvidersOptions,
+): Promise<Application> {
   const app = new Application()
   for (const provider of providers) app.use(provider)
-  await app.start()
+  await app.start(options)
   return app
 }

package/src/cli/index.ts

@@ -1,3 +1,3 @@
 export { bootstrap, shutdown, withProviders } from './bootstrap'
-export type { BootstrapResult } from './bootstrap'
+export type { BootstrapResult, WithProvidersOptions } from './bootstrap'
 export { default as CommandLoader } from './command_loader'

package/src/commands/queue_work.ts

@@ -1,9 +1,21 @@
 import type { Command } from 'commander'
 import chalk from 'chalk'
-import { bootstrap, shutdown } from '../cli/bootstrap.ts'
+import path from 'node:path'
+import { bootstrap, shutdown, withProviders } from '../cli/bootstrap.ts'
+import type Application from '@strav/kernel/core/application'
+import type ServiceProvider from '@strav/kernel/core/service_provider'
+import type Database from '@strav/database/database/database'
 import Queue from '@strav/queue/queue/queue'
+import QueueProvider from '@strav/queue/providers/queue_provider'
 import Worker from '@strav/queue/queue/worker'
 
+/**
+ * Conventional file the worker loads on start. Its top-level `Queue.handle(...)`
+ * calls register the job handlers, and its `providers` export lists the service
+ * providers the worker boots — mirroring `start/providers.ts` for the web entry.
+ */
+const JOBS_FILE = 'start/jobs.ts'
+
 export function register(program: Command): void {
   program
     .command('queue:work')
@@ -11,19 +23,67 @@ export function register(program: Command): void {
     .option('--queue <name>', 'Queue to process', 'default')
     .option('--sleep <ms>', 'Poll interval in milliseconds', '1000')
     .action(async options => {
-      let db
+      const queue = options.queue
+      const sleep = parseInt(options.sleep)
+
+      let app: Application | undefined
+      let db: Database | undefined
+
       try {
-        const { db: database, config } = await bootstrap()
-        db = database
+        const jobsPath = path.resolve(JOBS_FILE)
+
+        if (await Bun.file(jobsPath).exists()) {
+          // Importing start/jobs.ts runs its top-level Queue.handle(...) calls
+          // and exposes the provider list the worker needs. Booting those
+          // providers wires the facades (mail, notification, …) that handlers
+          // depend on — bootstrap() alone leaves them unregistered.
+          const jobs = await import(jobsPath)
+          const providers: ServiceProvider[] = Array.isArray(jobs.providers)
+            ? [...jobs.providers]
+            : []
+
+          if (providers.length === 0) {
+            throw new Error(
+              `${JOBS_FILE} must export a \`providers\` array — the service ` +
+                `providers the worker boots (ConfigProvider, DatabaseProvider, ` +
+                `QueueProvider, plus any facade providers your handlers use).`,
+            )
+          }
+
+          // QueueProvider wires the Queue singleton and ensures the tables —
+          // add it if the app's provider list left it out.
+          if (!providers.some(p => p.name === 'queue')) {
+            providers.push(new QueueProvider())
+          }
 
-        new Queue(db, config)
-        await Queue.ensureTables()
+          // signalHandlers: false — the Worker installs its own SIGINT/SIGTERM
+          // handlers that drain the in-flight job before start() returns. We
+          // call app.shutdown() only afterwards (in finally), so providers are
+          // never torn down while a job is still running.
+          app = await withProviders(providers, { signalHandlers: false })
+        } else {
+          console.warn(
+            chalk.yellow(`No ${JOBS_FILE} found — the worker has no registered handlers.`),
+          )
+          console.warn(
+            chalk.dim(
+              `  Create ${JOBS_FILE} with your Queue.handle(...) calls and a ` +
+                `\`providers\` export, or every dispatched job will fail.`,
+            ),
+          )
+          const { db: database, config } = await bootstrap()
+          db = database
+          new Queue(db, config)
+          await Queue.ensureTables()
+        }
 
-        const queue = options.queue
-        const sleep = parseInt(options.sleep)
+        const handlers = [...Queue.handlers.keys()]
 
         console.log(chalk.cyan(`Worker starting on queue "${queue}"...`))
         console.log(chalk.dim(`  poll interval: ${sleep}ms`))
+        console.log(
+          chalk.dim(`  handlers: ${handlers.length > 0 ? handlers.join(', ') : 'none'}`),
+        )
         console.log(chalk.dim('  Press Ctrl+C to stop.\n'))
 
         const worker = new Worker({ queue, sleep })
@@ -34,6 +94,7 @@ export function register(program: Command): void {
         console.error(chalk.red(`Error: ${err instanceof Error ? err.message : err}`))
         process.exit(1)
       } finally {
+        if (app) await app.shutdown()
         if (db) await shutdown(db)
       }
     })