@zintrust/core 0.1.26 → 0.1.28

package/src/cli/utils/EnvFileLoader.ts

@@ -0,0 +1,218 @@
+import { existsSync, readFileSync } from '@node-singletons/fs';
+import { join } from '@node-singletons/path';
+
+// NOTE: This module intentionally uses direct process.env[*] mutations
+// as its primary purpose is to load .env files and populate process.env
+// during application initialization. This is the only location where
+// such mutations should occur - all other code should use Env.get().
+
+type EnvMap = Record<string, string>;
+
+const normalizeAppMode = (value: string): string => {
+  const normalized = value.trim().toLowerCase();
+  if (normalized === 'production' || normalized === 'pro' || normalized === 'prod')
+    return 'production';
+  if (normalized === 'dev' || normalized === 'development') return 'dev';
+
+  // Per spec: any other value is treated as development.
+  return 'dev';
+};
+
+const stripInlineComment = (value: string): string => {
+  let inSingle = false;
+  let inDouble = false;
+
+  for (let i = 0; i < value.length; i += 1) {
+    const ch = value[i];
+    if (ch === "'" && !inDouble) inSingle = !inSingle;
+    if (ch === '"' && !inSingle) inDouble = !inDouble;
+
+    if (!inSingle && !inDouble && ch === '#') {
+      const prev = value[i - 1];
+      if (prev === undefined || prev === ' ' || prev === '\t') {
+        return value.slice(0, i).trimEnd();
+      }
+    }
+  }
+
+  return value;
+};
+
+const unquote = (value: string): string => {
+  const trimmed = value.trim();
+  if (trimmed.length >= 2) {
+    const first = trimmed[0];
+    const last = trimmed.at(-1);
+    if ((first === '"' && last === '"') || (first === "'" && last === "'")) {
+      return trimmed.slice(1, -1);
+    }
+  }
+  return trimmed;
+};
+
+const parseEnvFile = (raw: string): EnvMap => {
+  const result: EnvMap = {};
+  const lines = raw.split(/\r?\n/);
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (trimmed === '' || trimmed.startsWith('#')) continue;
+
+    const withoutExport = trimmed.startsWith('export ') ? trimmed.slice('export '.length) : trimmed;
+    const eq = withoutExport.indexOf('=');
+    if (eq <= 0) continue;
+
+    const key = withoutExport.slice(0, eq).trim();
+    if (key === '') continue;
+
+    const rhs = withoutExport.slice(eq + 1);
+    const withoutComment = stripInlineComment(rhs);
+    const value = unquote(withoutComment);
+
+    result[key] = value;
+  }
+
+  return result;
+};
+
+const applyToProcessEnv = (values: EnvMap, overrideExisting: boolean): void => {
+  for (const [key, value] of Object.entries(values)) {
+    if (!overrideExisting && typeof process.env[key] === 'string') continue;
+    process.env[key] = value;
+  }
+
+  // Compatibility helpers
+  if (typeof process.env['PORT'] !== 'string' && typeof process.env['APP_PORT'] === 'string') {
+    process.env['PORT'] = process.env['APP_PORT'];
+  }
+
+  if (typeof process.env['NODE_ENV'] !== 'string' && typeof process.env['APP_MODE'] === 'string') {
+    const mode = normalizeAppMode(process.env['APP_MODE']);
+    process.env['NODE_ENV'] = mode === 'production' ? 'production' : 'development';
+  }
+};
+
+const readEnvFileIfExists = (cwd: string, filename: string): EnvMap | undefined => {
+  const fullPath = join(cwd, filename);
+  if (!existsSync(fullPath)) return undefined;
+  const raw = readFileSync(fullPath, 'utf-8');
+  return parseEnvFile(raw);
+};
+
+const resolveAppMode = (cwd: string): string | undefined => {
+  const existing = process.env['APP_MODE'];
+  if (typeof existing === 'string' && existing.trim() !== '') return normalizeAppMode(existing);
+
+  const fromDotEnv = readEnvFileIfExists(cwd, '.env');
+  const value = fromDotEnv?.['APP_MODE'];
+  if (typeof value === 'string' && value.trim() !== '') return normalizeAppMode(value);
+
+  return undefined;
+};
+
+type LoadOptions = {
+  cwd?: string;
+  overrideExisting?: boolean;
+};
+
+type LoadState = {
+  loadedFiles: string[];
+  mode?: string;
+};
+
+type CliOverrides = {
+  nodeEnv?: 'development' | 'production' | 'testing';
+  port?: number;
+  runtime?: string;
+};
+
+const filesLoader = (cwd: string, mode: string | undefined): string[] => {
+  const files: string[] = [];
+  if (existsSync(join(cwd, '.env'))) files.push('.env');
+
+  // Per your rule: production uses .env; dev uses .env.dev
+  if (mode !== undefined && mode !== '' && mode !== 'production') {
+    const modeFile = `.env.${mode}`;
+    if (existsSync(join(cwd, modeFile))) files.push(modeFile);
+  }
+
+  const local = '.env.local';
+  if (existsSync(join(cwd, local))) files.push(local);
+
+  if (mode !== undefined && mode !== '') {
+    const modeLocal = `.env.${mode}.local`;
+    if (existsSync(join(cwd, modeLocal))) files.push(modeLocal);
+  }
+
+  return files;
+};
+
+let cached: LoadState | undefined;
+
+const load = (options: LoadOptions = {}): LoadState => {
+  if (cached !== undefined) return cached;
+
+  const cwd = typeof options.cwd === 'string' && options.cwd !== '' ? options.cwd : process.cwd();
+  const overrideExisting = options.overrideExisting ?? true;
+
+  const mode = resolveAppMode(cwd);
+
+  const files = filesLoader(cwd, mode);
+
+  let baseApplied = false;
+
+  for (const file of files) {
+    const parsed = readEnvFileIfExists(cwd, file);
+    if (!parsed) continue;
+
+    if (file === '.env') {
+      applyToProcessEnv(parsed, overrideExisting);
+      baseApplied = true;
+      continue;
+    }
+
+    // .env is primary: overlays only fill missing values and never override base.
+    applyToProcessEnv(parsed, baseApplied ? false : overrideExisting);
+  }
+
+  cached = { loadedFiles: files, mode };
+  return cached;
+};
+
+const ensureLoaded = (): LoadState => load({ overrideExisting: true });
+
+const applyCliOverrides = (overrides: CliOverrides): void => {
+  // Ensure base env is loaded first.
+  ensureLoaded();
+
+  if (typeof overrides.runtime === 'string' && overrides.runtime.trim() !== '') {
+    process.env['RUNTIME'] = overrides.runtime.trim();
+  }
+
+  if (typeof overrides.nodeEnv === 'string') {
+    process.env['NODE_ENV'] = overrides.nodeEnv;
+  }
+
+  if (typeof overrides.port === 'number') {
+    process.env['PORT'] = String(overrides.port);
+    process.env['APP_PORT'] = String(overrides.port);
+  }
+
+  // Keep PORT/APP_PORT in sync if only one exists.
+  if (typeof process.env['PORT'] !== 'string' && typeof process.env['APP_PORT'] === 'string') {
+    process.env['PORT'] = process.env['APP_PORT'];
+  }
+
+  if (typeof process.env['APP_PORT'] !== 'string' && typeof process.env['PORT'] === 'string') {
+    process.env['APP_PORT'] = process.env['PORT'];
+  }
+};
+
+const getState = (): LoadState => ensureLoaded();
+
+export const EnvFileLoader = Object.freeze({
+  load,
+  ensureLoaded,
+  applyCliOverrides,
+  getState,
+});

package/src/cli/utils/spawn.ts

@@ -0,0 +1,116 @@
+import { appConfig } from '@config/app';
+import { ErrorFactory } from '@exceptions/ZintrustError';
+import { spawn } from '@node-singletons/child-process';
+import { existsSync } from '@node-singletons/fs';
+import * as path from '@node-singletons/path';
+
+export interface SpawnAndWaitInput {
+  command: string;
+  args: string[];
+  cwd?: string;
+  env?: NodeJS.ProcessEnv;
+  forwardSignals?: boolean;
+}
+
+const getExitCode = (exitCode: number | null, signal: NodeJS.Signals | null): number => {
+  if (typeof exitCode === 'number') return exitCode;
+  if (signal === 'SIGINT' || signal === 'SIGTERM') return 0;
+  return 1;
+};
+
+const resolveLocalBin = (command: string, cwd: string): string => {
+  // If command is already a path, leave it alone.
+  if (command.includes('/') || command.includes('\\')) return command;
+
+  const binDir = path.join(cwd, 'node_modules', '.bin');
+  const candidates =
+    process.platform === 'win32'
+      ? [
+          path.join(binDir, `${command}.cmd`),
+          path.join(binDir, `${command}.exe`),
+          path.join(binDir, `${command}.bat`),
+          path.join(binDir, command),
+        ]
+      : [path.join(binDir, command)];
+
+  for (const candidate of candidates) {
+    if (existsSync(candidate)) return candidate;
+  }
+
+  return command;
+};
+
+export const SpawnUtil = Object.freeze({
+  async spawnAndWait(input: SpawnAndWaitInput): Promise<number> {
+    const cwd = input.cwd ?? process.cwd();
+    const resolvedCommand = resolveLocalBin(input.command, cwd);
+
+    const child = spawn(resolvedCommand, input.args, {
+      cwd,
+      env: input.env ?? appConfig.getSafeEnv(),
+      stdio: 'inherit',
+    });
+
+    // In interactive shells, the foreground process group already receives SIGINT
+    // (and often SIGTERM) so forwarding can cause duplicates. `tsx watch` is
+    // especially sensitive here and can print "Previous process hasn't exited yet. Force killing...".
+    const forwardSignals =
+      typeof input.forwardSignals === 'boolean' ? input.forwardSignals : !process.stdin.isTTY;
+
+    const forwardSignal = (signal: NodeJS.Signals): void => {
+      try {
+        child.kill(signal);
+      } catch (error) {
+        const wrapped = ErrorFactory.createTryCatchError(
+          'Failed to forward signal to child process',
+          error
+        );
+
+        // Best-effort logging; then rethrow (tests/assertions rely on this behavior).
+        try {
+          process.stderr.write(`${String(wrapped.message)}\n`);
+        } catch {
+          // ignore
+        }
+
+        throw wrapped;
+      }
+    };
+
+    const onSigint = (): void => forwardSignal('SIGINT');
+    const onSigterm = (): void => forwardSignal('SIGTERM');
+
+    if (forwardSignals) {
+      process.on('SIGINT', onSigint);
+      process.on('SIGTERM', onSigterm);
+    }
+
+    try {
+      const result = await new Promise<{ exitCode: number | null; signal: NodeJS.Signals | null }>(
+        (resolve, reject) => {
+          child.once('error', (error: unknown) => {
+            reject(error);
+          });
+
+          child.once('close', (code: number | null, signal: NodeJS.Signals | null) => {
+            resolve({ exitCode: code, signal });
+          });
+        }
+      );
+
+      return getExitCode(result.exitCode, result.signal);
+    } catch (error) {
+      const code = (error as NodeJS.ErrnoException | undefined)?.code;
+      if (code === 'ENOENT') {
+        throw ErrorFactory.createCliError(`Error: '${input.command}' not found on PATH.`);
+      }
+
+      throw ErrorFactory.createTryCatchError('Failed to spawn child process', error);
+    } finally {
+      if (forwardSignals) {
+        process.off('SIGINT', onSigint);
+        process.off('SIGTERM', onSigterm);
+      }
+    }
+  },
+});

package/src/cli/workers/QueueWorkRunner.ts

@@ -0,0 +1,377 @@
+/**
+ * Queue Work Runner
+ *
+ * Processes queued jobs via the framework CLI.
+ *
+ * BullMQ Compatibility:
+ * - Works with both basic queue drivers and BullMQ Redis driver
+ * - When QUEUE_DRIVER=redis, uses BullMQ enterprise features automatically
+ * - No changes needed - uses standard Queue API which is BullMQ-compatible
+ */
+import type { ReleaseCondition } from '@/types/Queue';
+import { Broadcast } from '@broadcast/Broadcast';
+import { Env } from '@config/env';
+import { Logger } from '@config/logger';
+import { queueConfig } from '@config/queue';
+import { ErrorFactory } from '@exceptions/ZintrustError';
+import { ZintrustLang } from '@lang/lang';
+import { Notification } from '@notification/Notification';
+import { createLockProvider, getLockProvider, registerLockProvider } from '@queue/LockProvider';
+import { Queue, resolveLockPrefix } from '@queue/Queue';
+import { registerQueuesFromRuntimeConfig } from '@queue/QueueRuntimeRegistration';
+
+export type QueueWorkKind = 'broadcast' | 'notification';
+
+type BroadcastPayload = {
+  type?: unknown;
+  channel: string;
+  event: string;
+  data: unknown;
+  timestamp?: number;
+  attempts?: number;
+};
+
+type NotificationPayload = {
+  type?: unknown;
+  recipient: string;
+  message: string;
+  options?: Record<string, unknown>;
+  timestamp?: number;
+  attempts?: number;
+};
+
+export type QueueWorkRunnerOptions = {
+  queueName: string;
+  kind?: QueueWorkKind;
+  driverName?: string;
+  timeoutSeconds?: number;
+  maxItems?: number;
+  /** Max retries after the first attempt (so total attempts = retry + 1) */
+  retry?: number;
+};
+
+export type QueueWorkRunnerResult = {
+  processed: number;
+  retried: number;
+  dropped: number;
+  notDueRequeued: number;
+  unknown: number;
+};
+
+const isKind = (value: unknown): value is QueueWorkKind =>
+  value === 'broadcast' || value === 'notification';
+
+const detectKindFromPayload = (payload: unknown): QueueWorkKind | undefined => {
+  if (payload !== null && typeof payload === 'object') {
+    const p = payload as Record<string, unknown>;
+    if (isKind(p['type'])) return p['type'];
+    if (typeof p['channel'] === 'string' && typeof p['event'] === 'string') return 'broadcast';
+    if (typeof p['recipient'] === 'string' && typeof p['message'] === 'string')
+      return 'notification';
+  }
+  return undefined;
+};
+
+const normalizeNumber = (value: unknown): number | undefined => {
+  if (typeof value === 'number' && Number.isFinite(value)) return value;
+  if (typeof value === 'string' && value.trim() !== '') {
+    const n = Number(value);
+    if (Number.isFinite(n)) return n;
+  }
+  return undefined;
+};
+
+const getTimestamp = (payload: Record<string, unknown>): number | undefined => {
+  return normalizeNumber(payload['timestamp']);
+};
+
+const getAttempts = (payload: Record<string, unknown>): number => {
+  const n = normalizeNumber(payload['attempts']);
+  return typeof n === 'number' && n >= 0 ? Math.floor(n) : 0;
+};
+
+const withAttempts = (
+  payload: Record<string, unknown>,
+  attempts: number
+): Record<string, unknown> => {
+  return { ...payload, attempts };
+};
+
+const shouldStop = (startedAtMs: number, timeoutSeconds?: number): boolean => {
+  if (timeoutSeconds === undefined) return false;
+  const elapsedMs = Date.now() - startedAtMs;
+  return elapsedMs >= timeoutSeconds * 1000;
+};
+
+type ProcessOutcome = 'continue' | 'break';
+
+const QUEUE_META_KEY = '__zintrustQueueMeta';
+
+type QueueMeta = {
+  deduplicationId?: string;
+  releaseAfter?: string | number | ReleaseCondition;
+  uniqueId?: string;
+};
+
+let lockProviderCache: ReturnType<typeof createLockProvider> | null = null;
+
+const getLockProviderForQueue = (): ReturnType<typeof createLockProvider> => {
+  if (lockProviderCache) return lockProviderCache;
+
+  const providerName = Env.get('QUEUE_LOCK_PROVIDER', ZintrustLang.REDIS).trim();
+  const prefix = resolveLockPrefix();
+  const defaultTtl = Env.getInt('QUEUE_DEFAULT_DEDUP_TTL', ZintrustLang.ZINTRUST_LOCKS_TTL);
+
+  const existing = getLockProvider(providerName);
+  if (existing) {
+    lockProviderCache = existing;
+    return existing;
+  }
+
+  const provider = createLockProvider({
+    type: providerName === ZintrustLang.REDIS ? ZintrustLang.REDIS : ZintrustLang.MEMORY,
+    prefix: prefix.length > 0 ? prefix : ZintrustLang.ZINTRUST_LOCKS_PREFIX,
+    defaultTtl,
+  });
+  registerLockProvider(providerName, provider);
+  // Also register under the literal memory name to ensure callers that expect
+  // a 'memory'-named provider (tests or other runtime code) can find it.
+  if (providerName !== ZintrustLang.MEMORY) {
+    try {
+      registerLockProvider(ZintrustLang.MEMORY, provider);
+    } catch {
+      // Best-effort: ignore registration errors to avoid breaking runtime logic.
+    }
+  }
+  lockProviderCache = provider;
+  return provider;
+};
+
+const extractQueueMeta = (
+  payload: Record<string, unknown>
+): { payload: Record<string, unknown>; meta?: QueueMeta } => {
+  const metaValue = payload[QUEUE_META_KEY];
+  if (metaValue !== undefined && metaValue !== null && typeof metaValue === 'object') {
+    const { [QUEUE_META_KEY]: metaRaw, ...rest } = payload;
+    return { payload: rest, meta: metaRaw as QueueMeta };
+  }
+
+  return { payload, meta: undefined };
+};
+
+const resolveConditionStatus = (condition: string): string | null => {
+  const normalized = condition.trim().toLowerCase();
+  if (normalized.includes('failed') || normalized.includes('error')) return 'failed';
+  if (normalized.includes('success') || normalized.includes('completed')) return 'success';
+
+  // Try to extract explicit comparison like: job.result.status === "completed"
+  const match = new RegExp(/status\s*={1,3}\s*['"]([a-z]+)['"]/).exec(normalized);
+  const capturedValue = match?.[1];
+  if (capturedValue !== null && capturedValue !== undefined && capturedValue.length > 0) {
+    const value = capturedValue;
+    if (value === 'failed' || value === 'error') return 'failed';
+    if (value === 'success' || value === 'completed') return 'success';
+  }
+
+  return null;
+};
+
+const shouldReleaseForOutcome = (
+  releaseAfter: QueueMeta['releaseAfter'],
+  outcome: 'success' | 'failed'
+): boolean => {
+  if (releaseAfter === 'success') return outcome === 'success';
+  if (releaseAfter === 'failed') return outcome === 'failed';
+  if (typeof releaseAfter === 'string') {
+    const normalized = releaseAfter.toLowerCase();
+    if (normalized.includes('failed') || normalized.includes('error')) return outcome === 'failed';
+    if (normalized.includes('success') || normalized.includes('completed'))
+      return outcome === 'success';
+    const fromCondition = resolveConditionStatus(normalized);
+    return fromCondition !== null && fromCondition === outcome;
+  }
+  if (releaseAfter !== null && releaseAfter !== undefined && typeof releaseAfter === 'object') {
+    const condition = String(releaseAfter.condition ?? '').toLowerCase();
+    const fromCondition = resolveConditionStatus(condition);
+    return fromCondition !== null && fromCondition === outcome;
+  }
+  return false;
+};
+
+const releaseLockAfterResult = async (
+  meta: QueueMeta | undefined,
+  outcome: 'success' | 'failed'
+): Promise<void> => {
+  if (meta === undefined) return;
+  const deduplicationId = meta.deduplicationId;
+  if (deduplicationId === undefined || deduplicationId === null) {
+    return;
+  }
+  const deduplicationKey = String(deduplicationId).trim();
+  if (deduplicationKey === '') return;
+  const releaseAfter = meta.releaseAfter;
+  if (releaseAfter === undefined || releaseAfter === null || releaseAfter === '') return;
+  if (!shouldReleaseForOutcome(releaseAfter, outcome)) return;
+
+  const provider = getLockProviderForQueue();
+  const doRelease = async (): Promise<void> => {
+    const status = await provider.status(deduplicationKey);
+    if (!status.exists) return;
+    await provider.release({
+      key: deduplicationKey,
+      ttl: status.ttl ?? 0,
+      acquired: true,
+      expires: status.expires ?? new Date(),
+    });
+  };
+
+  const delay =
+    typeof releaseAfter === 'object' && typeof releaseAfter.delay === 'number'
+      ? releaseAfter.delay
+      : 0;
+
+  if (delay > 0) {
+    const timeoutId = globalThis.setTimeout(() => {
+      void doRelease();
+    }, delay);
+    timeoutId.unref();
+  } else {
+    await doRelease();
+  }
+};
+
+const processMessage = async (
+  options: QueueWorkRunnerOptions,
+  msg: { id: string; payload: Record<string, unknown> },
+  maxAttempts: number,
+  result: QueueWorkRunnerResult
+): Promise<ProcessOutcome> => {
+  const payload = msg.payload ?? {};
+  const { payload: payloadWithoutMeta, meta } = extractQueueMeta(payload);
+  const kind = options.kind ?? detectKindFromPayload(payloadWithoutMeta);
+
+  if (kind === undefined) {
+    Logger.warn('Queue worker: unknown job payload; dropping', {
+      queue: options.queueName,
+      messageId: msg.id,
+      payloadKeys: Object.keys(payload),
+    });
+    result.unknown++;
+    await Queue.ack(options.queueName, msg.id, options.driverName);
+    return 'continue';
+  }
+
+  const timestamp = getTimestamp(payloadWithoutMeta);
+  if (typeof timestamp === 'number' && timestamp > Date.now()) {
+    // Not due yet: re-enqueue and stop after rotating the head once.
+    const payloadForRequeue = meta
+      ? { ...payloadWithoutMeta, [QUEUE_META_KEY]: meta }
+      : payloadWithoutMeta;
+    await Queue.enqueue(options.queueName, payloadForRequeue, options.driverName);
+    await Queue.ack(options.queueName, msg.id, options.driverName);
+    result.notDueRequeued++;
+    return 'break';
+  }
+
+  const attempts = getAttempts(payloadWithoutMeta);
+
+  try {
+    if (kind === 'broadcast') {
+      const job = payloadWithoutMeta as unknown as BroadcastPayload;
+      await Broadcast.send(job.channel, job.event, job.data);
+    } else {
+      const job = payloadWithoutMeta as unknown as NotificationPayload;
+      await Notification.send(job.recipient, job.message, job.options ?? {});
+    }
+
+    await releaseLockAfterResult(meta, 'success');
+
+    await Queue.ack(options.queueName, msg.id, options.driverName);
+    result.processed++;
+    return 'continue';
+  } catch (error) {
+    const nextAttempts = attempts + 1;
+    const canRetry = nextAttempts < maxAttempts;
+
+    Logger.error('Queue worker: job failed', {
+      queue: options.queueName,
+      kind,
+      messageId: msg.id,
+      attempts: nextAttempts,
+      maxAttempts,
+      error,
+    });
+
+    if (canRetry) {
+      const payloadForRetry = meta
+        ? { ...payloadWithoutMeta, [QUEUE_META_KEY]: meta }
+        : payloadWithoutMeta;
+      await Queue.enqueue(
+        options.queueName,
+        withAttempts(payloadForRetry, nextAttempts),
+        options.driverName
+      );
+      result.retried++;
+    } else {
+      await releaseLockAfterResult(meta, 'failed');
+      result.dropped++;
+    }
+
+    await Queue.ack(options.queueName, msg.id, options.driverName);
+    return 'continue';
+  }
+};
+
+export const QueueWorkRunner = Object.freeze({
+  async run(options: QueueWorkRunnerOptions): Promise<QueueWorkRunnerResult> {
+    registerQueuesFromRuntimeConfig(queueConfig);
+
+    const startedAtMs = Date.now();
+
+    const maxItems = typeof options.maxItems === 'number' ? options.maxItems : 1000;
+    const timeoutSeconds = typeof options.timeoutSeconds === 'number' ? options.timeoutSeconds : 10;
+    const maxRetries = typeof options.retry === 'number' ? options.retry : 3;
+    const maxAttempts = Math.max(0, Math.floor(maxRetries)) + 1;
+
+    const result: QueueWorkRunnerResult = {
+      processed: 0,
+      retried: 0,
+      dropped: 0,
+      notDueRequeued: 0,
+      unknown: 0,
+    };
+
+    /* eslint-disable no-await-in-loop */
+    while (result.processed < maxItems && !shouldStop(startedAtMs, timeoutSeconds)) {
+      const msg = await Queue.dequeue<Record<string, unknown>>(
+        options.queueName,
+        options.driverName
+      );
+      if (msg === undefined) break;
+
+      const outcome = await processMessage(
+        options,
+        { id: msg.id, payload: msg.payload ?? {} },
+        maxAttempts,
+        result
+      );
+      if (outcome === 'break') break;
+    }
+    /* eslint-enable no-await-in-loop */
+
+    return result;
+  },
+
+  parseKind(value: unknown): QueueWorkKind {
+    const v = String(value ?? '')
+      .trim()
+      .toLowerCase();
+    if (v === 'broadcast' || v === 'broad') return 'broadcast';
+    if (v === 'notification' || v === 'notify') return 'notification';
+    throw ErrorFactory.createCliError(
+      `Invalid kind '${String(value)}'. Expected 'broadcast' or 'notification'.`
+    );
+  },
+});
+
+export default QueueWorkRunner;