@nmakarov/cli-toolkit 0.68.0 → 0.70.0

package/dist/tasks.cjs

@@ -34,6 +34,7 @@ __export(tasks_exports, {
   LOOP_RUNTIME_KEYS: () => LOOP_RUNTIME_KEYS,
   SERVICE_TASK_NAMES: () => SERVICE_TASK_NAMES,
   TaskGetLogs: () => TaskGetLogs,
+  TaskPauseRunner: () => TaskPauseRunner,
   TaskPing: () => TaskPing,
   TaskSampleProcess: () => TaskSampleProcess,
   TaskSetRuntimeParam: () => TaskSetRuntimeParam,
@@ -41,9 +42,11 @@ __export(tasks_exports, {
   TaskStopRunner: () => TaskStopRunner,
   TaskSumAB: () => TaskSumAB,
   TaskSystemInfo: () => TaskSystemInfo,
+  TaskUnpauseRunner: () => TaskUnpauseRunner,
   TasksManager: () => TasksManager,
   TasksRegistry: () => TasksRegistry,
   appendTaskIpcLog: () => appendTaskIpcLog,
+  applyRunnerPaused: () => applyRunnerPaused,
   applyRuntimeParam: () => applyRuntimeParam,
   applyRuntimePatch: () => applyRuntimePatch,
   coerceRuntimeValue: () => coerceRuntimeValue,
@@ -428,12 +431,13 @@ function tasksSchemaSpec(queueName = "tasks") {
     }
   };
 }
-function taskHistoryInsertFromQueueRow(row, overrides) {
+function taskHistoryInsertFromQueueRow(row, overrides = {}) {
   const { id, ...snapshot } = row;
-  void id;
+  const opid = overrides.opid !== void 0 ? overrides.opid : snapshot.opid != null && String(snapshot.opid).trim() !== "" ? snapshot.opid : id;
   return {
     ...snapshot,
-    ...overrides
+    ...overrides,
+    opid
   };
 }
 async function ensureTaskTables(context, options = {}) {
@@ -2772,69 +2776,6 @@ var TaskStopRunner = class extends AbstractTask {
   }
 };
 
-// src/tasks/coreTasks/TaskGetLogs.js
-var TaskGetLogs = class extends AbstractTask {
-  /**
-   * @param {object} context
-   * @param {Record<string, unknown>} [overrides]
-   * @returns {Promise<{ source: string, resource: string, tail: number, afterTs?: string }>}
-   */
-  static async resolveCustomParams(context, overrides = {}) {
-    const merged = AbstractTask._mergeTypedParams(context, "task-get-logs", {
-      source: "string",
-      resource: "string",
-      tail: "number default 100",
-      afterTs: "string"
-    }, overrides);
-    const source = typeof merged.source === "string" ? merged.source.trim() : "";
-    const resource = typeof merged.resource === "string" ? merged.resource.trim() : "";
-    if (!source) throw new ParamError('getLogs: param "source" is required');
-    if (!resource) throw new ParamError('getLogs: param "resource" is required');
-    let tail = Number(merged.tail);
-    if (!Number.isFinite(tail) || tail < 1) tail = 100;
-    tail = Math.min(1e4, Math.max(1, Math.floor(tail)));
-    const out = { source, resource, tail };
-    if (typeof merged.afterTs === "string" && merged.afterTs.trim()) {
-      out.afterTs = merged.afterTs.trim();
-    }
-    return out;
-  }
-  /**
-   * @param {unknown} _reportProgress Unused (single-shot read, no progress events).
-   * @returns {Promise<{ success: boolean, results: unknown }>}
-   */
-  async run(_reportProgress) {
-    const p = this.task.params ?? {};
-    const source = String(p.source ?? "").trim();
-    const resource = String(p.resource ?? "").trim();
-    const tail = Math.max(1, Math.min(1e4, Number(p.tail) > 0 ? Number(p.tail) : 100));
-    const afterTs = p.afterTs != null && String(p.afterTs).trim() ? String(p.afterTs).trim() : null;
-    if (!source || !resource) {
-      return {
-        success: false,
-        results: { error: 'getLogs requires params "source" and "resource"' }
-      };
-    }
-    try {
-      const { records, latestTs } = await readTaskIpcLogsSnapshot(this.context, {
-        source,
-        resource,
-        tail,
-        afterTs
-      });
-      return {
-        success: true,
-        results: { records, latestTs, source, resource }
-      };
-    } catch (e) {
-      return {
-        success: false,
-        results: { error: e?.message ?? String(e) }
-      };
-    }
-  }
-};
-
 // src/tasks/runtimeParams.js
 var LOOP_RUNTIME_KEYS = ["maxParallel", "pollMs", "claimJitterMs", "scanLimit"];
 var LOGGER_RUNTIME_KEYS = [
@@ -2848,7 +2789,16 @@ var LOGGER_RUNTIME_KEYS = [
   "progressWithTimes",
   "progressThrottleMs"
 ];
-var CONTROL_LANE_TASK_NAMES = ["stopRunner", "stop", "setRuntimeParam", "setRunnerParam"];
+var CONTROL_LANE_TASK_NAMES = [
+  "stopRunner",
+  "stop",
+  "pauseRunner",
+  "pause",
+  "unpauseRunner",
+  "unpause",
+  "setRuntimeParam",
+  "setRunnerParam"
+];
 function controlLaneTaskNames(extra) {
   const names = [...CONTROL_LANE_TASK_NAMES];
   if (extra == null || extra === "") return names;
@@ -2911,6 +2861,7 @@ function ensureTasksRuntime(context, seed = {}) {
   if (rt.pollMs === void 0) rt.pollMs = seed.pollMs ?? 1e3;
   if (rt.claimJitterMs === void 0) rt.claimJitterMs = seed.claimJitterMs ?? 0;
   if (rt.scanLimit === void 0) rt.scanLimit = seed.scanLimit ?? 100;
+  if (rt.paused === void 0) rt.paused = seed.paused === true;
   return rt;
 }
 async function applyRuntimeParam(context, key, value) {
@@ -2975,6 +2926,140 @@ function readLoopRuntime(context) {
   };
 }
 
+// src/tasks/coreTasks/TaskPauseRunner.js
+async function applyRunnerPaused(context, paused) {
+  const runtime = ensureTasksRuntime(context);
+  const was = runtime.paused === true;
+  runtime.paused = paused === true;
+  const registry = context.servicesRegistry;
+  if (registry && typeof registry === "object") {
+    await updateServicesRegistryMetadata(context, registry, {
+      paused: runtime.paused,
+      pausedAt: runtime.paused ? (/* @__PURE__ */ new Date()).toISOString() : null
+    });
+  }
+  const message = runtime.paused ? was ? "Runner already paused (no new worker tasks)." : "Runner paused: finishing in-flight work; no new worker tasks until unpause." : was ? "Runner unpaused: claiming worker tasks again." : "Runner already running (not paused).";
+  context.logger?.warn?.(
+    runtime.paused ? `[TaskPauseRunner] ${message}` : `[TaskUnpauseRunner] ${message}`
+  );
+  return {
+    success: true,
+    results: {
+      paused: runtime.paused,
+      message
+    }
+  };
+}
+var TaskPauseRunner = class extends AbstractTask {
+  static taskName = "pauseRunner";
+  static description = "Pause a runner: finish in-flight tasks, claim no new worker tasks until unpaused";
+  static aliases = ["pause"];
+  static defaultWaitForResult = true;
+  /**
+   * @param {object} context
+   * @param {Record<string, unknown>} [overrides]
+   * @returns {Promise<object>}
+   */
+  static async resolveParams(context, overrides = {}) {
+    const main = await super.resolveParams(context, overrides);
+    if (!main.serviceName) {
+      throw new ParamError(
+        "pause/pauseRunner requires --serviceName (registry instance name; optional --serviceGroup, --instanceNumber, --serverName to narrow targeting)"
+      );
+    }
+    return main;
+  }
+  async run() {
+    return applyRunnerPaused(this.context, true);
+  }
+};
+var TaskUnpauseRunner = class extends AbstractTask {
+  static taskName = "unpauseRunner";
+  static description = "Unpause a runner: resume claiming worker tasks";
+  static aliases = ["unpause"];
+  static defaultWaitForResult = true;
+  /**
+   * @param {object} context
+   * @param {Record<string, unknown>} [overrides]
+   * @returns {Promise<object>}
+   */
+  static async resolveParams(context, overrides = {}) {
+    const main = await super.resolveParams(context, overrides);
+    if (!main.serviceName) {
+      throw new ParamError(
+        "unpause/unpauseRunner requires --serviceName (registry instance name; optional --serviceGroup, --instanceNumber, --serverName to narrow targeting)"
+      );
+    }
+    return main;
+  }
+  async run() {
+    return applyRunnerPaused(this.context, false);
+  }
+};
+
+// src/tasks/coreTasks/TaskGetLogs.js
+var TaskGetLogs = class extends AbstractTask {
+  /**
+   * @param {object} context
+   * @param {Record<string, unknown>} [overrides]
+   * @returns {Promise<{ source: string, resource: string, tail: number, afterTs?: string }>}
+   */
+  static async resolveCustomParams(context, overrides = {}) {
+    const merged = AbstractTask._mergeTypedParams(context, "task-get-logs", {
+      source: "string",
+      resource: "string",
+      tail: "number default 100",
+      afterTs: "string"
+    }, overrides);
+    const source = typeof merged.source === "string" ? merged.source.trim() : "";
+    const resource = typeof merged.resource === "string" ? merged.resource.trim() : "";
+    if (!source) throw new ParamError('getLogs: param "source" is required');
+    if (!resource) throw new ParamError('getLogs: param "resource" is required');
+    let tail = Number(merged.tail);
+    if (!Number.isFinite(tail) || tail < 1) tail = 100;
+    tail = Math.min(1e4, Math.max(1, Math.floor(tail)));
+    const out = { source, resource, tail };
+    if (typeof merged.afterTs === "string" && merged.afterTs.trim()) {
+      out.afterTs = merged.afterTs.trim();
+    }
+    return out;
+  }
+  /**
+   * @param {unknown} _reportProgress Unused (single-shot read, no progress events).
+   * @returns {Promise<{ success: boolean, results: unknown }>}
+   */
+  async run(_reportProgress) {
+    const p = this.task.params ?? {};
+    const source = String(p.source ?? "").trim();
+    const resource = String(p.resource ?? "").trim();
+    const tail = Math.max(1, Math.min(1e4, Number(p.tail) > 0 ? Number(p.tail) : 100));
+    const afterTs = p.afterTs != null && String(p.afterTs).trim() ? String(p.afterTs).trim() : null;
+    if (!source || !resource) {
+      return {
+        success: false,
+        results: { error: 'getLogs requires params "source" and "resource"' }
+      };
+    }
+    try {
+      const { records, latestTs } = await readTaskIpcLogsSnapshot(this.context, {
+        source,
+        resource,
+        tail,
+        afterTs
+      });
+      return {
+        success: true,
+        results: { records, latestTs, source, resource }
+      };
+    } catch (e) {
+      return {
+        success: false,
+        results: { error: e?.message ?? String(e) }
+      };
+    }
+  }
+};
+
 // src/tasks/coreTasks/TaskSetRuntimeParam.js
 var TaskSetRuntimeParam = class extends AbstractTask {
   static defaultWaitForResult = true;
@@ -3130,7 +3215,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("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("getLogs", TaskGetLogs).add("setRuntimeParam", TaskSetRuntimeParam).add("setRunnerParam", TaskSetRuntimeParam);
   }
   /**
    * Register a single task class under a name. Overwrites any previous entry.
@@ -3233,6 +3318,10 @@ var SERVICE_TASK_NAMES = [
   "ping",
   "stop",
   "stopRunner",
+  "pause",
+  "pauseRunner",
+  "unpause",
+  "unpauseRunner",
   "shellCommand",
   "systemInfo",
   "info",
@@ -3698,6 +3787,7 @@ async function runTasksLoop(context, options) {
     const defaultMeta = {
       component: "tasks-runner",
       allowedTasks: allowedTasks?.length ? allowedTasks.join(",") : "all",
+      paused: false,
       runtime: {
         maxParallel: loop0.maxParallel,
         pollMs: loop0.pollMs,
@@ -3764,28 +3854,38 @@ async function runTasksLoop(context, options) {
       if (claimJitterMs > 0) {
         await sleepMs(Math.floor(Math.random() * (claimJitterMs + 1)));
       }
-      while (runningPromises.size < maxParallel) {
-        const claimed = await claimNextRunnableTask(
-          context,
-          tasksTable,
-          target,
-          registry,
-          scanLimit,
-          allowedTasks,
-          runnerIdentity
-        );
-        if (!claimed) break;
-        const p = executeClaimedTask(context, tasksTable, historyTable, claimed, registry, runningTaskInstances).then(async (outcome) => {
-          if (outcome.stopRunnerRequested && !stopRequested) {
-            stopRequested = true;
-            stopAllowanceMs = outcome.stopAllowanceMs || stopAllowanceMs;
-            context.tasksRunnerStop = true;
-            await signalRunningTasksStop(context, runningTaskInstances, stopAllowanceMs);
-          }
-        }).finally(() => {
-          runningPromises.delete(p);
-        });
-        runningPromises.add(p);
+      const paused = context.tasksRuntime?.paused === true;
+      if (!paused) {
+        while (runningPromises.size < maxParallel) {
+          const claimed = await claimNextRunnableTask(
+            context,
+            tasksTable,
+            target,
+            registry,
+            scanLimit,
+            allowedTasks,
+            runnerIdentity
+          );
+          if (!claimed) break;
+          const p = executeClaimedTask(
+            context,
+            tasksTable,
+            historyTable,
+            claimed,
+            registry,
+            runningTaskInstances
+          ).then(async (outcome) => {
+            if (outcome.stopRunnerRequested && !stopRequested) {
+              stopRequested = true;
+              stopAllowanceMs = outcome.stopAllowanceMs || stopAllowanceMs;
+              context.tasksRunnerStop = true;
+              await signalRunningTasksStop(context, runningTaskInstances, stopAllowanceMs);
+            }
+          }).finally(() => {
+            runningPromises.delete(p);
+          });
+          runningPromises.add(p);
+        }
       }
       const wakePromises = [...runningPromises];
       if (runningControlPromise) {
@@ -3839,16 +3939,26 @@ async function waitForTaskResult(context, taskId, options = {}) {
   const pollMs = options.pollMs ?? 500;
   const { tasksTable, historyTable } = queueToTableNames(queueName);
   const deadline = Date.now() + timeoutMs;
-  const waitStartedAt = /* @__PURE__ */ new Date();
-  let cachedNameOpid = null;
-  async function historySinceWait(name, opid) {
-    let q = db(historyTable).where({ name }).where("completed_at", ">=", waitStartedAt);
+  const waitStartedAt = new Date(Date.now() - 5e3);
+  let cachedNameOpid = options.name != null && String(options.name).trim() !== "" ? {
+    name: String(options.name).trim(),
+    opid: options.opid !== void 0 ? options.opid : null
+  } : null;
+  async function findHistory(name, opid) {
+    const base = () => db(historyTable).where({ name }).where("completed_at", ">=", waitStartedAt);
+    if (opid != null && String(opid).trim() !== "") {
+      const byOpid = await base().where({ opid }).orderBy("completed_at", "desc").first();
+      if (byOpid) return byOpid;
+    }
+    const byQueueId = await base().where({ opid: taskId }).orderBy("completed_at", "desc").first();
+    if (byQueueId) return byQueueId;
+    const byQueueIdAny = await db(historyTable).where({ name, opid: taskId }).orderBy("completed_at", "desc").first();
+    if (byQueueIdAny) return byQueueIdAny;
     if (opid == null || opid === "") {
-      q = q.whereNull("opid");
-    } else {
-      q = q.where({ opid });
+      const byNull = await base().whereNull("opid").orderBy("completed_at", "desc").first();
+      if (byNull) return byNull;
     }
-    return await q.orderBy("completed_at", "desc").first();
+    return void 0;
   }
   while (Date.now() <= deadline) {
     const legacy = await db(historyTable).where({ id: taskId }).orderBy("created_at", "desc").first();
@@ -3858,18 +3968,17 @@ async function waitForTaskResult(context, taskId, options = {}) {
     const pending = await db(tasksTable).where({ id: taskId }).first();
     if (pending) {
       cachedNameOpid = { name: pending.name, opid: pending.opid };
-      const done = await historySinceWait(pending.name, pending.opid);
-      if (done) {
-        return done;
-      }
-    } else if (cachedNameOpid) {
-      const done = await historySinceWait(cachedNameOpid.name, cachedNameOpid.opid);
+    }
+    if (cachedNameOpid) {
+      const done = await findHistory(cachedNameOpid.name, cachedNameOpid.opid);
       if (done) {
         return done;
       }
-      return null;
     } else {
-      return null;
+      const byQueueId = await db(historyTable).where({ opid: taskId }).orderBy("completed_at", "desc").first();
+      if (byQueueId) {
+        return byQueueId;
+      }
     }
     await sleepMs(pollMs);
   }
@@ -4014,6 +4123,7 @@ var TasksManager = class _TasksManager {
   LOOP_RUNTIME_KEYS,
   SERVICE_TASK_NAMES,
   TaskGetLogs,
+  TaskPauseRunner,
   TaskPing,
   TaskSampleProcess,
   TaskSetRuntimeParam,
@@ -4021,9 +4131,11 @@ var TasksManager = class _TasksManager {
   TaskStopRunner,
   TaskSumAB,
   TaskSystemInfo,
+  TaskUnpauseRunner,
   TasksManager,
   TasksRegistry,
   appendTaskIpcLog,
+  applyRunnerPaused,
   applyRuntimeParam,
   applyRuntimePatch,
   coerceRuntimeValue,