@nmakarov/cli-toolkit 0.25.0 → 0.29.0

package/dist/cli-runner.cjs

@@ -1758,46 +1758,87 @@ var Params = class _Params {
   paramGetters = [];
   trackedParams = [];
   _currentModule = "script";
-  /** Resolved early in constructor so cleanup does not read params lazily */
-  _showUsedParams = false;
+  /**
+   * Resolved early in constructor so cleanup does not read params lazily.
+   * One of: false (off) | "end" (print at exit) | "top" (print after init,
+   * via context.showUsedParamsIfNeeded()) | "stop" (print after init, then
+   * exit the process — also via context.showUsedParamsIfNeeded()).
+   */
+  _showUsedParamsMode = false;
+  /** Guard so the dump prints at most once (top OR end, never both). */
+  _usedParamsPrinted = false;
   constructor(context, options = {}) {
     this.context = context;
     this.args = context.args;
     if (Object.keys(options).length > 0) {
       this.configure(options);
     }
-    this._showUsedParams = this.get("showUsedParams", "boolean default false");
+    this._resolveShowUsedParams();
     if (context && typeof context.registerCleanup === "function") {
       context.registerCleanup((ctx) => {
-        if (!ctx.params.getShowUsedParams()) return;
-        const byModule = ctx.params.getFiguredByModule();
-        const modules = Object.keys(byModule).sort();
-        if (modules.length === 0) return;
-        const logger = ctx.logger;
-        logger.debug("[Params]: list of used params:");
-        if (typeof logger.highlight !== "function") {
-          for (const mod of modules) {
-            logger.debug(`  [${mod}]`);
-            for (const [key, entry] of Object.entries(byModule[mod])) {
-              logger.debug(`    ${key}: ${JSON.stringify(entry.value)} (${entry.source})`);
-            }
-          }
-          return;
-        }
-        for (const mod of modules) {
-          logger.debug(`  [${mod}]`);
-          for (const [key, entry] of Object.entries(byModule[mod])) {
-            const valueStr = JSON.stringify(entry.value);
-            const display = entry.source === "default" ? valueStr : logger.highlight(valueStr);
-            logger.debug(`    ${key}: ${display} (${entry.source})`);
-          }
-        }
+        if (!ctx.params.getShowUsedParamsMode()) return;
+        ctx.params.printUsedParams(ctx.logger);
       });
     }
   }
-  /** Whether --showUsedParams was requested (resolved in constructor). */
+  /**
+   * Resolve the --showUsedParams mode. The flag is intentionally dual-typed:
+   *   (absent) / --no-showUsedParams / =false   -> false  (off)
+   *   --showUsedParams / =true                   -> "end"  (print at exit)
+   *   --showUsedParams=top                       -> "top"  (print after init)
+   *   --showUsedParams=stop                      -> "stop" (print after init, then exit)
+   * Read raw (uncoerced) from args so the string "top"/"stop" isn't forced to
+   * a boolean, then track it under the "script" module for the dump itself.
+   */
+  _resolveShowUsedParams() {
+    const raw = this.args.get("showUsedParams");
+    const source = this.args.getSource?.("showUsedParams") ?? "default";
+    let mode = false;
+    if (raw === void 0 || raw === null) {
+      mode = false;
+    } else if (typeof raw === "string" && raw.trim().toLowerCase() === "top") {
+      mode = "top";
+    } else if (typeof raw === "string" && raw.trim().toLowerCase() === "stop") {
+      mode = "stop";
+    } else {
+      const s = typeof raw === "string" ? raw.trim().toLowerCase() : raw;
+      const falsey = s === false || s === "false" || s === "0" || s === "no" || s === "off";
+      mode = falsey ? false : "end";
+    }
+    this._showUsedParamsMode = mode;
+    this.trackParam("showUsedParams", "string", mode, raw === void 0 ? "default" : source, "script");
+    return mode;
+  }
+  /** Whether --showUsedParams was requested in any mode (truthy = on). */
   getShowUsedParams() {
-    return this._showUsedParams;
+    return this._showUsedParamsMode !== false;
+  }
+  /** Resolved mode: false | "end" | "top" | "stop". */
+  getShowUsedParamsMode() {
+    return this._showUsedParamsMode;
+  }
+  /**
+   * Print the module-grouped list of figured params (the --showUsedParams
+   * dump). Idempotent: only the first call prints, so callers can invoke it
+   * at the top (long-running services) without double-printing at exit.
+   */
+  printUsedParams(logger) {
+    if (this._usedParamsPrinted) return;
+    const byModule = this.getFiguredByModule();
+    const modules = Object.keys(byModule).sort();
+    if (modules.length === 0) return;
+    this._usedParamsPrinted = true;
+    logger = logger ?? this.context?.logger ?? console;
+    const hasHighlight = typeof logger.highlight === "function";
+    logger.debug("[Params]: list of used params:");
+    for (const mod of modules) {
+      logger.debug(`  [${mod}]`);
+      for (const [key, entry] of Object.entries(byModule[mod])) {
+        const valueStr = JSON.stringify(entry.value);
+        const display = hasHighlight && entry.source !== "default" ? logger.highlight(valueStr) : valueStr;
+        logger.debug(`    ${key}: ${display} (${entry.source})`);
+      }
+    }
   }
   /**
    * Configure parameters
@@ -2482,7 +2523,25 @@ function setup(opts = {}) {
     emitter: partialContext.emitter,
     isStop: partialContext.isStop,
     cleanupFunctions: partialContext.cleanupFunctions,
-    registerCleanup: partialContext.registerCleanup
+    registerCleanup: partialContext.registerCleanup,
+    // For long-running scripts (servers): with --showUsedParams=top, print
+    // the used-params list now (after the script has initialized all its
+    // own components), instead of at exit. No-op for the default mode,
+    // which prints at exit via the cleanup registered by Params.
+    //
+    // --showUsedParams=stop behaves like "top" but then exits immediately —
+    // a quick "show me the figured params and quit" that skips the flow's
+    // actual work. Like --stopAfter=init, this is a hard exit(0) (registered
+    // cleanups are skipped); call it once components/params are resolved.
+    showUsedParamsIfNeeded: () => {
+      const mode = params.getShowUsedParamsMode?.();
+      if (mode !== "top" && mode !== "stop") return;
+      params.printUsedParams(logger);
+      if (mode === "stop") {
+        logger.debug?.("[showUsedParams=stop] params printed \u2014 exiting");
+        process.exit(0);
+      }
+    }
   };
   logger.debug("[setup] completed successfully");
   return context;
@@ -2549,15 +2608,19 @@ async function init(flow2, opts = {}) {
       process.exit(0);
     }
     let sigintCount = 0;
+    let firstSigintAt = 0;
     process.on("SIGINT", async () => {
       if (!context) return;
-      sigintCount += 1;
-      if (sigintCount === 1) {
+      const now = Date.now();
+      if (sigintCount === 0) {
+        sigintCount = 1;
+        firstSigintAt = now;
         stop = true;
         context.logger.info(`>> emitting stop with allowance ${stopAllowance}`);
         context.emitter.emit("stop", stopAllowance);
         return;
       }
+      if (now - firstSigintAt < 250) return;
       context.logger.warn("[process] second SIGINT: running cleanup then exit");
       await runRegisteredCleanups(context);
       process.exit(2);
@@ -3195,7 +3258,7 @@ function defineTasksTable(t, db, tableNameForIndex) {
   t.timestamp("past_due").defaultTo(null);
   t.text("name").notNullable();
   t.text("opid");
-  t.json("params");
+  t.jsonb("params");
   t.text("service_group");
   t.integer("instance_number");
   t.text("service_name");
@@ -3204,7 +3267,7 @@ function defineTasksTable(t, db, tableNameForIndex) {
   t.timestamp("status_changed_at").defaultTo(null);
   t.text("progress");
   t.boolean("success");
-  t.json("results");
+  t.jsonb("results");
   t.index(["service_group", "status", "priority", "created_at"], `${tableNameForIndex}_claim_idx`);
   t.index(["service_group", "name"], `${tableNameForIndex}_group_name_idx`);
 }
@@ -3219,11 +3282,29 @@ function taskHistoryInsertFromQueueRow(row, overrides) {
 async function ensureTaskTables(context, options = {}) {
   const queueName = options.queueName ?? "tasks";
   const recreate = options.recreate ?? false;
+  const dryRun = options.dryRun ?? false;
   const db = getDb(context);
+  const log = context.logger ?? console;
   const { tasksTable, historyTable, registryTable } = queueToTableNames(queueName);
   const needsTasks = recreate ? true : !await db.tableExists(tasksTable);
   const needsHistory = recreate ? true : !await db.tableExists(historyTable);
   const needsRegistry = recreate ? true : !await db.tableExists(registryTable);
+  if (dryRun) {
+    const plan = [];
+    if (recreate) {
+      plan.push(`DROP TABLE IF EXISTS ${historyTable}, ${tasksTable}, ${registryTable}`);
+    }
+    if (needsTasks) plan.push(`CREATE TABLE ${tasksTable} (tasks queue)`);
+    if (needsHistory) plan.push(`CREATE TABLE ${historyTable} (history mirror)`);
+    if (needsRegistry) plan.push(`CREATE TABLE ${registryTable} (services registry)`);
+    if (plan.length === 0) {
+      log.info?.(`[tasks-schema] dryRun \u2014 queue "${queueName}" already up to date; no DDL`);
+    } else {
+      log.info?.(`[tasks-schema] dryRun \u2014 would run ${plan.length} statement(s) for queue "${queueName}":`);
+      for (const s of plan) log.info?.(`  - ${s}`);
+    }
+    return;
+  }
   if (recreate) {
     await db.schema.dropTableIfExists(historyTable);
     await db.schema.dropTableIfExists(tasksTable);
@@ -5646,9 +5727,8 @@ async function executeClaimedTask(context, tasksTable, historyTable, row, regist
     const dbName = String(context?.params?.get?.("dbName") || "local");
     const tableName = String(context?.params?.get?.("table") || "tasks");
     const fallbackRecoverCommand = [
-      "npx",
-      "tsx",
-      "examples/tasks/recover-task.ts",
+      "node",
+      "examples/tasks/recover-task.js",
       `--dbName='${dbName.replace(/'/g, `'\\''`)}'`,
       `--table='${tableName.replace(/'/g, `'\\''`)}'`,
       `--id='${String(row.id).replace(/'/g, `'\\''`)}'`
@@ -5714,6 +5794,8 @@ async function claimNextRunnableTask(context, tasksTable, serviceGroup, registry
   const db = getDb3(context);
   let query = db(tasksTable).where({ status: "idle" }).where(function() {
     this.whereNull("service_group").orWhere({ service_group: serviceGroup });
+  }).where(function() {
+    this.whereNull("next_run_at").orWhere("next_run_at", "<=", db.fn.now());
   }).orderByRaw("CASE WHEN past_due IS NULL THEN 1 ELSE 0 END ASC").orderBy([{ column: "priority", order: "asc" }]).orderByRaw("CASE WHEN completed_at IS NULL THEN 0 ELSE 1 END ASC").orderBy([{ column: "completed_at", order: "asc" }, { column: "created_at", order: "asc" }]).limit(scanLimit);
   if (taskNames && taskNames.length > 0) {
     query = query.whereIn("name", taskNames);