@nmakarov/cli-toolkit 0.72.0 → 0.75.0

package/dist/cli-runner.js

@@ -2794,6 +2794,7 @@ function setup(opts = {}) {
   const partialContext = {
     emitter: new EventEmitter(),
     isStop: () => false,
+    isKill: () => false,
     cleanupFunctions: [],
     registerCleanup: (fn) => {
       partialContext.cleanupFunctions.push(fn);
@@ -2815,6 +2816,7 @@ function setup(opts = {}) {
     logger,
     emitter: partialContext.emitter,
     isStop: partialContext.isStop,
+    isKill: partialContext.isKill,
     cleanupFunctions: partialContext.cleanupFunctions,
     registerCleanup: partialContext.registerCleanup,
     // For long-running scripts (servers): with --showUsedParams=top, print
@@ -2864,6 +2866,7 @@ function printAllParameters(context) {
 }
 async function init(flow2, opts = {}) {
   let stop = false;
+  let kill = false;
   let context = null;
   let cleanupRan = false;
   const runRegisteredCleanups = async (ctx) => {
@@ -2893,6 +2896,7 @@ async function init(flow2, opts = {}) {
     }
     context = setup(opts);
     context.isStop = () => stop;
+    context.isKill = () => kill;
     context = await setupModules(context, opts);
     const stopAfter = context.args.get("stopAfter");
     const stopAllowanceSec = Number(context.params.get("stopAllowance", "number default 60"));
@@ -2931,6 +2935,14 @@ async function init(flow2, opts = {}) {
       );
       context.emitter.emit("stop", stopAllowanceMs);
     });
+    process.on("SIGUSR2", () => {
+      if (!context || kill) return;
+      kill = true;
+      stop = true;
+      context.logger.warn(">> SIGUSR2: emitting kill (urgent stop)");
+      context.emitter.emit("kill");
+      context.emitter.emit("stop", stopAllowanceMs);
+    });
     await flow2(context);
   } catch (error) {
     const errorLocation = error instanceof Error && error.stack ? error.stack.split("\n")[1]?.trim() || "Unknown location" : "Unknown location";
@@ -2957,7 +2969,7 @@ async function init(flow2, opts = {}) {
     }
     if (process.exitCode && process.exitCode !== 0) {
       process.exit(process.exitCode);
-    } else if (stop) {
+    } else if (stop || kill) {
       process.exit(0);
     }
   }
@@ -5855,6 +5867,8 @@ var AbstractTask = class _AbstractTask {
   constructor(context, task) {
     this.context = context;
     this.task = task;
+    this._stopRequested = false;
+    this._pauseRequested = false;
   }
   /**
    * Return a short reason string when the task should be deferred (e.g. "locked
@@ -5872,6 +5886,26 @@ var AbstractTask = class _AbstractTask {
    * @param {number} [_allowanceMs] Grace period the runner promises before hard exit.
    */
   requestStop(_allowanceMs) {
+    this._stopRequested = true;
+  }
+  /**
+   * Cooperative pause signal (from `pauseTask` control-lane task). Long-running
+   * tasks should finish the current unit of work, persist a checkpoint, and
+   * return `{ success: true, results: { taskPaused: true, … } }` so the runner
+   * keeps the row as `status=paused` instead of deleting it.
+   *
+   * @param {number} [_allowanceMs]
+   */
+  requestPause(_allowanceMs) {
+    this._pauseRequested = true;
+  }
+  /** @returns {boolean} */
+  isStopRequested() {
+    return this._stopRequested === true;
+  }
+  /** @returns {boolean} */
+  isPauseRequested() {
+    return this._pauseRequested === true;
   }
   /**
    * Perform the task. Must be implemented by subclasses.
@@ -6570,6 +6604,8 @@ var CONTROL_LANE_TASK_NAMES = [
   "pause",
   "unpauseRunner",
   "unpause",
+  "pauseTask",
+  "resumeTask",
   "setRuntimeParam",
   "setRunnerParam"
 ];
@@ -6774,6 +6810,190 @@ var TaskUnpauseRunner = class extends AbstractTask {
   }
 };
 
+// src/tasks/coreTasks/TaskPauseTask.js
+function parseProgressObject(progress) {
+  if (progress == null || progress === "") return {};
+  if (typeof progress === "object" && !Array.isArray(progress)) {
+    return { ...progress };
+  }
+  if (typeof progress === "string") {
+    const t = progress.trim();
+    if (t.startsWith("{") || t.startsWith("[")) {
+      try {
+        const parsed = JSON.parse(t);
+        if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) return { ...parsed };
+      } catch {
+      }
+    }
+    return { message: progress };
+  }
+  return { message: String(progress) };
+}
+async function applyPauseTask(context, taskId) {
+  const db = context.db;
+  if (!db) throw new Error("pauseTask: context.db is required");
+  const id = String(taskId ?? "").trim();
+  if (!id) throw new ParamError('pauseTask: param "taskId" is required');
+  const { tasksTable } = queueToTableNames(context.tasksQueueName ?? "tasks");
+  const row = await db(tasksTable).where({ id }).first();
+  if (!row) {
+    return { success: false, results: { error: `Task ${id} not found`, taskId: id } };
+  }
+  if (row.status === "paused") {
+    return {
+      success: true,
+      results: { taskId: id, status: "paused", message: "Task already paused" }
+    };
+  }
+  if (row.status === "idle") {
+    const progress = parseProgressObject(row.progress);
+    progress.pauseRequested = true;
+    progress.pausedAt = (/* @__PURE__ */ new Date()).toISOString();
+    await db(tasksTable).where({ id }).update({
+      status: "paused",
+      status_changed_at: db.fn.now(),
+      progress: toJsonColumn(progress)
+    });
+    context.logger?.warn?.(`[pauseTask] idle task ${id} (${row.name}) \u2192 paused`);
+    return {
+      success: true,
+      results: { taskId: id, status: "paused", message: "Idle task paused" }
+    };
+  }
+  if (row.status === "running") {
+    const progress = parseProgressObject(row.progress);
+    progress.pauseRequested = true;
+    progress.pauseRequestedAt = (/* @__PURE__ */ new Date()).toISOString();
+    await db(tasksTable).where({ id }).update({
+      progress: toJsonColumn(progress)
+    });
+    const inst = context.runningTaskInstances?.get?.(id);
+    if (inst && typeof inst.requestPause === "function") {
+      await inst.requestPause();
+      context.logger?.warn?.(
+        `[pauseTask] signaled running task ${id} (${row.name}) to pause after current unit`
+      );
+      return {
+        success: true,
+        results: {
+          taskId: id,
+          status: "running",
+          signaled: true,
+          message: "Pause requested; task will finish current unit then park as paused"
+        }
+      };
+    }
+    context.logger?.warn?.(
+      `[pauseTask] stamped pauseRequested on ${id} (${row.name}) \u2014 not running in this process`
+    );
+    return {
+      success: true,
+      results: {
+        taskId: id,
+        status: "running",
+        signaled: false,
+        message: "pauseRequested stamped on task row; target runner must observe it (enqueue pauseTask on that service)"
+      }
+    };
+  }
+  return {
+    success: false,
+    results: {
+      error: `Cannot pause task in status "${row.status}"`,
+      taskId: id,
+      status: row.status
+    }
+  };
+}
+async function applyResumeTask(context, taskId) {
+  const db = context.db;
+  if (!db) throw new Error("resumeTask: context.db is required");
+  const id = String(taskId ?? "").trim();
+  if (!id) throw new ParamError('resumeTask: param "taskId" is required');
+  const { tasksTable } = queueToTableNames(context.tasksQueueName ?? "tasks");
+  const row = await db(tasksTable).where({ id }).first();
+  if (!row) {
+    return { success: false, results: { error: `Task ${id} not found`, taskId: id } };
+  }
+  if (row.status === "idle") {
+    return {
+      success: true,
+      results: { taskId: id, status: "idle", message: "Task already idle (runnable)" }
+    };
+  }
+  if (row.status !== "paused") {
+    return {
+      success: false,
+      results: {
+        error: `Cannot resume task in status "${row.status}" (expected paused)`,
+        taskId: id,
+        status: row.status
+      }
+    };
+  }
+  const progress = parseProgressObject(row.progress);
+  delete progress.pauseRequested;
+  delete progress.pauseRequestedAt;
+  delete progress.pausedAt;
+  progress.resumedAt = (/* @__PURE__ */ new Date()).toISOString();
+  await db(tasksTable).where({ id }).update({
+    status: "idle",
+    status_changed_at: db.fn.now(),
+    started_at: null,
+    completed_at: null,
+    success: null,
+    progress: toJsonColumn(progress),
+    // Clear claim binding so any matching worker can pick it up.
+    service_name: null,
+    server_name: null,
+    instance_number: null,
+    next_run_at: null
+  });
+  context.logger?.warn?.(`[resumeTask] paused task ${id} (${row.name}) \u2192 idle`);
+  return {
+    success: true,
+    results: { taskId: id, status: "idle", message: "Task resumed (idle; will be claimed)" }
+  };
+}
+var TaskPauseTask = class extends AbstractTask {
+  static taskName = "pauseTask";
+  static description = "Pause a specific task: finish current unit, persist status=paused";
+  static defaultWaitForResult = true;
+  static async resolveCustomParams(context, overrides = {}) {
+    const merged = AbstractTask._mergeTypedParams(
+      context,
+      "task-pause-task",
+      { taskId: "string" },
+      overrides
+    );
+    const taskId = typeof merged.taskId === "string" ? merged.taskId.trim() : "";
+    if (!taskId) throw new ParamError('pauseTask: param "taskId" is required');
+    return { taskId };
+  }
+  async run() {
+    return applyPauseTask(this.context, this.task?.params?.taskId);
+  }
+};
+var TaskResumeTask = class extends AbstractTask {
+  static taskName = "resumeTask";
+  static description = "Resume a paused task (status paused \u2192 idle)";
+  static defaultWaitForResult = true;
+  static async resolveCustomParams(context, overrides = {}) {
+    const merged = AbstractTask._mergeTypedParams(
+      context,
+      "task-resume-task",
+      { taskId: "string" },
+      overrides
+    );
+    const taskId = typeof merged.taskId === "string" ? merged.taskId.trim() : "";
+    if (!taskId) throw new ParamError('resumeTask: param "taskId" is required');
+    return { taskId };
+  }
+  async run() {
+    return applyResumeTask(this.context, this.task?.params?.taskId);
+  }
+};
+
 // src/tasks/coreTasks/TaskGetLogs.js
 var TaskGetLogs = class extends AbstractTask {
   /**
@@ -6992,7 +7212,7 @@ var TasksRegistry = class _TasksRegistry {
    * @returns {TasksRegistry}
    */
   static withCoreTasks() {
-    return new _TasksRegistry().add("ping", TaskPing).add("sampleProcess", TaskSampleProcess).add("shellCommand", TaskShellCommand).add("systemInfo", TaskSystemInfo).add("info", TaskSystemInfo).add("taskSumAB", TaskSumAB).add("stopRunner", TaskStopRunner).add("stop", TaskStopRunner).add("pauseRunner", TaskPauseRunner).add("pause", TaskPauseRunner).add("unpauseRunner", TaskUnpauseRunner).add("unpause", TaskUnpauseRunner).add("getLogs", TaskGetLogs).add("setRuntimeParam", TaskSetRuntimeParam).add("setRunnerParam", TaskSetRuntimeParam);
+    return new _TasksRegistry().add("ping", TaskPing).add("sampleProcess", TaskSampleProcess).add("shellCommand", TaskShellCommand).add("systemInfo", TaskSystemInfo).add("info", TaskSystemInfo).add("taskSumAB", TaskSumAB).add("stopRunner", TaskStopRunner).add("stop", TaskStopRunner).add("pauseRunner", TaskPauseRunner).add("pause", TaskPauseRunner).add("unpauseRunner", TaskUnpauseRunner).add("unpause", TaskUnpauseRunner).add("pauseTask", TaskPauseTask).add("resumeTask", TaskResumeTask).add("getLogs", TaskGetLogs).add("setRuntimeParam", TaskSetRuntimeParam).add("setRunnerParam", TaskSetRuntimeParam);
   }
   /**
    * Register a single task class under a name. Overwrites any previous entry.
@@ -7184,11 +7404,12 @@ async function executeClaimedTask(context, tasksTable, historyTable, row, regist
   } finally {
     runningTaskInstances.delete(row.id);
   }
+  const taskPaused = success && results && typeof results === "object" && results.taskPaused === true;
   await db(historyTable).insert(
     taskHistoryInsertFromQueueRow(row, {
       completed_at: /* @__PURE__ */ new Date(),
       success,
-      status: success ? "completed" : "failed",
+      status: taskPaused ? "paused" : success ? "completed" : "failed",
       status_changed_at: db.fn.now(),
       params: toJsonColumn(row.params),
       results: toJsonColumn(results)
@@ -7211,7 +7432,24 @@ async function executeClaimedTask(context, tasksTable, historyTable, row, regist
       details: results
     });
   }
-  if (row.schedule) {
+  if (taskPaused) {
+    const checkpointParams = results.checkpointParams && typeof results.checkpointParams === "object" ? results.checkpointParams : row.params;
+    const progressPayload = results.progress != null ? results.progress : { paused: true, pausedAt: (/* @__PURE__ */ new Date()).toISOString(), message: "paused" };
+    await db(tasksTable).where({ id: row.id }).update({
+      started_at: null,
+      completed_at: /* @__PURE__ */ new Date(),
+      success: true,
+      results: toJsonColumn(results),
+      params: toJsonColumn(checkpointParams),
+      progress: toJsonColumn(progressPayload),
+      status: "paused",
+      status_changed_at: db.fn.now(),
+      past_due: null,
+      service_name: null,
+      server_name: null,
+      instance_number: null
+    });
+  } else if (row.schedule) {
     if (success) {
       let nextRunAt = null;
       try {
@@ -7339,6 +7577,7 @@ async function runTasksLoop(context, options) {
   }
   const runningPromises = /* @__PURE__ */ new Set();
   const runningTaskInstances = /* @__PURE__ */ new Map();
+  context.runningTaskInstances = runningTaskInstances;
   let runningControlPromise = null;
   let stopRequested = false;
   let stopAllowanceMs = Number(context.stopAllowanceMs) > 0 ? Number(context.stopAllowanceMs) : 6e4;