@nmakarov/cli-toolkit 0.72.0 → 0.73.0

package/dist/tasks.cjs

@@ -36,7 +36,9 @@ __export(tasks_exports, {
   SERVICE_TASK_NAMES: () => SERVICE_TASK_NAMES,
   TaskGetLogs: () => TaskGetLogs,
   TaskPauseRunner: () => TaskPauseRunner,
+  TaskPauseTask: () => TaskPauseTask,
   TaskPing: () => TaskPing,
+  TaskResumeTask: () => TaskResumeTask,
   TaskSampleProcess: () => TaskSampleProcess,
   TaskSetRuntimeParam: () => TaskSetRuntimeParam,
   TaskShellCommand: () => TaskShellCommand,
@@ -47,6 +49,8 @@ __export(tasks_exports, {
   TasksManager: () => TasksManager,
   TasksRegistry: () => TasksRegistry,
   appendTaskIpcLog: () => appendTaskIpcLog,
+  applyPauseTask: () => applyPauseTask,
+  applyResumeTask: () => applyResumeTask,
   applyRunnerPaused: () => applyRunnerPaused,
   applyRuntimeParam: () => applyRuntimeParam,
   applyRuntimePatch: () => applyRuntimePatch,
@@ -2141,6 +2145,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
@@ -2158,6 +2164,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.
@@ -2864,6 +2890,8 @@ var CONTROL_LANE_TASK_NAMES = [
   "pause",
   "unpauseRunner",
   "unpause",
+  "pauseTask",
+  "resumeTask",
   "setRuntimeParam",
   "setRunnerParam"
 ];
@@ -3068,6 +3096,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 {
   /**
@@ -3286,7 +3498,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.
@@ -3393,6 +3605,8 @@ var SERVICE_TASK_NAMES = [
   "pauseRunner",
   "unpause",
   "unpauseRunner",
+  "pauseTask",
+  "resumeTask",
   "shellCommand",
   "systemInfo",
   "info",
@@ -3688,11 +3902,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)
@@ -3715,7 +3930,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 {
@@ -3843,6 +4075,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;
@@ -4203,7 +4436,9 @@ var TasksManager = class _TasksManager {
   SERVICE_TASK_NAMES,
   TaskGetLogs,
   TaskPauseRunner,
+  TaskPauseTask,
   TaskPing,
+  TaskResumeTask,
   TaskSampleProcess,
   TaskSetRuntimeParam,
   TaskShellCommand,
@@ -4214,6 +4449,8 @@ var TasksManager = class _TasksManager {
   TasksManager,
   TasksRegistry,
   appendTaskIpcLog,
+  applyPauseTask,
+  applyResumeTask,
   applyRunnerPaused,
   applyRuntimeParam,
   applyRuntimePatch,