@nmakarov/cli-toolkit 0.49.0 → 0.51.0

package/dist/tasks.cjs

@@ -30,10 +30,13 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var tasks_exports = {};
 __export(tasks_exports, {
   AbstractTask: () => AbstractTask,
+  LOGGER_RUNTIME_KEYS: () => LOGGER_RUNTIME_KEYS,
+  LOOP_RUNTIME_KEYS: () => LOOP_RUNTIME_KEYS,
   SERVICE_TASK_NAMES: () => SERVICE_TASK_NAMES,
   TaskGetLogs: () => TaskGetLogs,
   TaskPing: () => TaskPing,
   TaskSampleProcess: () => TaskSampleProcess,
+  TaskSetRuntimeParam: () => TaskSetRuntimeParam,
   TaskShellCommand: () => TaskShellCommand,
   TaskStopRunner: () => TaskStopRunner,
   TaskSumAB: () => TaskSumAB,
@@ -41,11 +44,16 @@ __export(tasks_exports, {
   TasksManager: () => TasksManager,
   TasksRegistry: () => TasksRegistry,
   appendTaskIpcLog: () => appendTaskIpcLog,
+  applyRuntimeParam: () => applyRuntimeParam,
+  applyRuntimePatch: () => applyRuntimePatch,
+  coerceRuntimeValue: () => coerceRuntimeValue,
+  controlLaneTaskNames: () => controlLaneTaskNames,
   convertPattern: () => convertPattern,
   defaultTasksRegistry: () => defaultTasksRegistry,
   enqueueStopTask: () => enqueueStopTask,
   enqueueTask: () => enqueueTask,
   ensureTaskTables: () => ensureTaskTables,
+  ensureTasksRuntime: () => ensureTasksRuntime,
   flushTaskIpcLogs: () => flushTaskIpcLogs,
   ipcFileLogsTableNameForSourceResource: () => ipcFileLogsTableNameForSourceResource,
   listAliveRunnerHeartbeats: () => listServicesRegistry,
@@ -55,6 +63,7 @@ __export(tasks_exports, {
   nextTimeMatch: () => nextTimeMatch,
   normalizeAllowedTasks: () => normalizeAllowedTasks,
   queueToTableNames: () => queueToTableNames,
+  readLoopRuntime: () => readLoopRuntime,
   readTaskIpcLogsSnapshot: () => readTaskIpcLogsSnapshot,
   registerInServicesRegistry: () => registerInServicesRegistry,
   registerRunnerHeartbeat: () => registerInServicesRegistry,
@@ -2783,6 +2792,273 @@ var TaskGetLogs = class extends AbstractTask {
   }
 };
 
+// src/tasks/runtimeParams.js
+var LOOP_RUNTIME_KEYS = ["maxParallel", "pollMs", "claimJitterMs", "scanLimit"];
+var LOGGER_RUNTIME_KEYS = [
+  "levels",
+  "silent",
+  "showLevel",
+  "timestamp",
+  "mode",
+  "route",
+  "prefix",
+  "progressWithTimes",
+  "progressThrottleMs"
+];
+var CONTROL_LANE_TASK_NAMES = ["stopRunner", "stop", "setRuntimeParam", "setRunnerParam"];
+function controlLaneTaskNames() {
+  return [...CONTROL_LANE_TASK_NAMES];
+}
+function asPositiveInt(value, key, { min = 1 } = {}) {
+  const n = Number(value);
+  if (!Number.isFinite(n) || n < min) {
+    throw new ParamError(
+      `setRuntimeParam: ${key} must be a number >= ${min} (got ${JSON.stringify(value)})`
+    );
+  }
+  return Math.floor(n);
+}
+function coerceRuntimeValue(key, value) {
+  switch (key) {
+    case "maxParallel":
+      return asPositiveInt(value, key, { min: 1 });
+    case "pollMs":
+      return asPositiveInt(value, key, { min: 50 });
+    case "claimJitterMs":
+      return asPositiveInt(value, key, { min: 0 });
+    case "scanLimit":
+      return asPositiveInt(value, key, { min: 1 });
+    case "silent":
+    case "showLevel":
+    case "timestamp":
+    case "progressWithTimes":
+      if (typeof value === "boolean") return value;
+      if (value === "true" || value === "1") return true;
+      if (value === "false" || value === "0") return false;
+      throw new ParamError(
+        `setRuntimeParam: ${key} must be boolean (got ${JSON.stringify(value)})`
+      );
+    case "progressThrottleMs":
+      return asPositiveInt(value, key, { min: 0 });
+    case "levels":
+    case "mode":
+    case "route":
+    case "prefix":
+      return value;
+    default:
+      return value;
+  }
+}
+function ensureTasksRuntime(context, seed = {}) {
+  if (!context.tasksRuntime || typeof context.tasksRuntime !== "object") {
+    context.tasksRuntime = {};
+  }
+  const rt = context.tasksRuntime;
+  if (rt.maxParallel === void 0) rt.maxParallel = seed.maxParallel ?? 32;
+  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;
+  return rt;
+}
+async function applyRuntimeParam(context, key, value) {
+  const k = String(key ?? "").trim();
+  if (!k) throw new ParamError("setRuntimeParam: key is required");
+  const runtime = ensureTasksRuntime(context);
+  const next = coerceRuntimeValue(k, value);
+  const previous = runtime[k];
+  const applied = [];
+  runtime[k] = next;
+  applied.push("tasksRuntime");
+  if (LOGGER_RUNTIME_KEYS.includes(k) && context.logger?.configure) {
+    context.logger.configure({ [k]: next });
+    applied.push("logger");
+  }
+  const hook = context.tasksRuntimeOnParam;
+  if (typeof hook === "function") {
+    await hook(k, next, runtime, context);
+    applied.push("onRuntimeParam");
+  }
+  const reg = context.servicesRegistry;
+  if (reg?.rowId && reg?.registryTable) {
+    try {
+      const loopSnapshot = {};
+      for (const lk of LOOP_RUNTIME_KEYS) {
+        if (runtime[lk] !== void 0) loopSnapshot[lk] = runtime[lk];
+      }
+      await updateServicesRegistryMetadata(context, reg, {
+        runtime: loopSnapshot,
+        runtimeUpdatedAt: (/* @__PURE__ */ new Date()).toISOString()
+      });
+      applied.push("servicesRegistry");
+    } catch (err) {
+      context.logger?.warn?.(
+        `[setRuntimeParam] registry metadata update failed: ${err?.message ?? String(err)}`
+      );
+    }
+  }
+  return { key: k, previous, next, applied };
+}
+async function applyRuntimePatch(context, patch) {
+  if (!patch || typeof patch !== "object" || Array.isArray(patch)) {
+    throw new ParamError("setRuntimeParam: patch must be a plain object");
+  }
+  const entries = Object.entries(patch);
+  if (entries.length === 0) {
+    throw new ParamError("setRuntimeParam: patch is empty");
+  }
+  const out = [];
+  for (const [key, value] of entries) {
+    out.push(await applyRuntimeParam(context, key, value));
+  }
+  return out;
+}
+function readLoopRuntime(context) {
+  const rt = ensureTasksRuntime(context);
+  return {
+    maxParallel: Math.max(1, Number(rt.maxParallel) || 1),
+    pollMs: Math.max(50, Number(rt.pollMs) || 1e3),
+    claimJitterMs: Math.max(0, Number(rt.claimJitterMs) || 0),
+    scanLimit: Math.max(1, Number(rt.scanLimit) || 100)
+  };
+}
+
+// src/tasks/coreTasks/TaskSetRuntimeParam.js
+var TaskSetRuntimeParam = class extends AbstractTask {
+  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 && !main.serviceGroup) {
+      throw new ParamError(
+        "setRuntimeParam requires --serviceName (one instance) or --serviceGroup (broadcast to alive instances)"
+      );
+    }
+    return main;
+  }
+  /**
+   * @param {object} context
+   * @param {Record<string, unknown>} [overrides]
+   * @returns {Promise<{ key?: string, value?: unknown, patch?: Record<string, unknown> }>}
+   */
+  static async resolveCustomParams(context, overrides = {}) {
+    const merged = AbstractTask._mergeTypedParams(
+      context,
+      "task-set-runtime-param",
+      {
+        paramKey: "string",
+        paramValue: "string",
+        key: "string",
+        value: "string"
+      },
+      overrides
+    );
+    if (merged.patch && typeof merged.patch === "object" && !Array.isArray(merged.patch)) {
+      if (Object.keys(merged.patch).length === 0) {
+        throw new ParamError("setRuntimeParam: patch is empty");
+      }
+      return { patch: { ...merged.patch } };
+    }
+    const key = merged.paramKey || merged.key;
+    const value = merged.paramValue !== void 0 ? merged.paramValue : merged.value;
+    if (!key) {
+      throw new ParamError(
+        `setRuntimeParam requires --paramKey/--paramValue, or --paramsJson '{"key":"maxParallel","value":16}' / '{"patch":{...}}'`
+      );
+    }
+    let parsed = value;
+    if (typeof value === "string") {
+      const t = value.trim();
+      if (t === "true") parsed = true;
+      else if (t === "false") parsed = false;
+      else if (t !== "" && !Number.isNaN(Number(t)) && /^-?\d+(\.\d+)?$/.test(t)) {
+        parsed = Number(t);
+      } else if (t.startsWith("{") && t.endsWith("}") || t.startsWith("[") && t.endsWith("]") || t.startsWith('"') && t.endsWith('"')) {
+        try {
+          parsed = JSON.parse(t);
+        } catch {
+          parsed = value;
+        }
+      }
+    }
+    return { key: String(key), value: parsed };
+  }
+  /**
+   * Enqueue one or many setRuntimeParam tasks. Prefer this over a bare
+   * `enqueueTask` when broadcasting to a service group.
+   *
+   * @param {object} context
+   * @param {Record<string, unknown>} [overrides]
+   * @returns {Promise<{ ids: string[], targets: string[] }>}
+   */
+  static async enqueue(context, overrides = {}) {
+    const payload = await this.resolveParams(context, { ...overrides, name: "setRuntimeParam" });
+    const queueName = payload.queueName ?? "tasks";
+    if (payload.serviceName) {
+      const id = await enqueueTask(context, payload);
+      return { ids: [id], targets: [payload.serviceName] };
+    }
+    const group = String(payload.serviceGroup || "").trim();
+    if (!group) {
+      throw new ParamError("setRuntimeParam.enqueue: serviceGroup required for broadcast");
+    }
+    const alive = await listServicesRegistry(context, {
+      queueName,
+      serviceGroup: group,
+      staleMs: overrides.staleMs ?? 45e3
+    });
+    if (!alive.length) {
+      throw new ParamError(
+        `setRuntimeParam: no alive services in group="${group}" queue="${queueName}"`
+      );
+    }
+    const ids = [];
+    const targets = [];
+    for (const reg of alive) {
+      const id = await enqueueTask(context, {
+        ...payload,
+        serviceGroup: group,
+        serviceName: reg.service_name,
+        serverName: reg.server_name ?? null,
+        instanceNumber: reg.instance_number ?? null
+      });
+      ids.push(id);
+      targets.push(reg.service_name);
+    }
+    context.logger?.info?.(
+      `[setRuntimeParam] broadcast to ${targets.length} instance(s) in group=${group}: ${targets.join(", ")}`
+    );
+    return { ids, targets };
+  }
+  /**
+   * @returns {Promise<{ success: true, results: object }>}
+   */
+  async run() {
+    const params = this.task?.params ?? {};
+    let changes;
+    if (params.patch && typeof params.patch === "object") {
+      changes = await applyRuntimePatch(this.context, params.patch);
+    } else {
+      changes = [await applyRuntimeParam(this.context, params.key, params.value)];
+    }
+    const summary = changes.map((c) => `${c.key}: ${JSON.stringify(c.previous)} \u2192 ${JSON.stringify(c.next)}`);
+    this.context.logger.warn?.(
+      `[TaskSetRuntimeParam] applied on ${this.context.servicesRegistry?.serviceName ?? "runner"}: ${summary.join("; ")}`
+    );
+    return {
+      success: true,
+      results: {
+        runtimeParamApplied: true,
+        changes,
+        runtime: { ...this.context.tasksRuntime ?? {} }
+      }
+    };
+  }
+};
+
 // src/tasks/TasksRegistry.js
 var TasksRegistry = class _TasksRegistry {
   /**
@@ -2801,7 +3077,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);
+    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);
   }
   /**
    * Register a single task class under a name. Overwrites any previous entry.
@@ -2907,7 +3183,9 @@ var SERVICE_TASK_NAMES = [
   "shellCommand",
   "systemInfo",
   "info",
-  "getLogs"
+  "getLogs",
+  "setRuntimeParam",
+  "setRunnerParam"
 ];
 function normalizeAllowedTasks(value) {
   if (!value) return void 0;
@@ -3334,18 +3612,23 @@ async function claimNextRunnableTask(context, tasksTable, serviceGroup, registry
 async function runTasksLoop(context, options) {
   const queueName = options.queueName ?? "tasks";
   const target = options.target;
-  const pollMs = options.pollMs ?? 1e3;
-  const claimJitterMs = options.claimJitterMs ?? 0;
-  const maxParallel = options.maxParallel ?? 32;
-  const scanLimit = options.scanLimit ?? 100;
   const allowedTasks = normalizeAllowedTasks(options.allowedTasks);
   const registry = normalizeRegistry(options.registry);
   const { tasksTable, historyTable } = queueToTableNames(queueName);
   if (!target) throw new Error("runTasksLoop: target is required");
   context.tasksQueueName = queueName;
+  ensureTasksRuntime(context, {
+    maxParallel: options.maxParallel ?? 32,
+    pollMs: options.pollMs ?? 1e3,
+    claimJitterMs: options.claimJitterMs ?? 0,
+    scanLimit: options.scanLimit ?? 100
+  });
+  if (typeof options.onRuntimeParam === "function") {
+    context.tasksRuntimeOnParam = options.onRuntimeParam;
+  }
   const runningPromises = /* @__PURE__ */ new Set();
   const runningTaskInstances = /* @__PURE__ */ new Map();
-  let runningStopControlPromise = null;
+  let runningControlPromise = null;
   let stopRequested = false;
   let stopAllowanceMs = 5e3;
   context.tasksRunnerStop = false;
@@ -3356,9 +3639,16 @@ async function runTasksLoop(context, options) {
   if (hbGroup) {
     const hbIntervalMs = options.runnerHeartbeatIntervalMs ?? 1e4;
     const staleMs = options.runnerHeartbeatStaleMs ?? 45e3;
+    const loop0 = readLoopRuntime(context);
     const defaultMeta = {
       component: "tasks-runner",
-      allowedTasks: allowedTasks?.length ? allowedTasks.join(",") : "all"
+      allowedTasks: allowedTasks?.length ? allowedTasks.join(",") : "all",
+      runtime: {
+        maxParallel: loop0.maxParallel,
+        pollMs: loop0.pollMs,
+        claimJitterMs: loop0.claimJitterMs,
+        scanLimit: loop0.scanLimit
+      }
     };
     registryReg = await registerInServicesRegistry(context, {
       queueName,
@@ -3371,6 +3661,7 @@ async function runTasksLoop(context, options) {
       enforceMaxInstances: options.runnerEnforceMaxInstances ?? true,
       metadata: options.runnerMetadata ?? defaultMeta
     });
+    context.servicesRegistry = registryReg;
     runnerIdentity = {
       service_name: registryReg.serviceName,
       server_name: import_node_os3.default.hostname(),
@@ -3384,22 +3675,23 @@ async function runTasksLoop(context, options) {
   }
   try {
     while (!context.isStop() && !stopRequested && context.tasksRunnerStop !== true) {
-      if (!runningStopControlPromise) {
-        const claimedStopTask = await claimNextRunnableTask(
+      const { maxParallel, pollMs, claimJitterMs, scanLimit } = readLoopRuntime(context);
+      if (!runningControlPromise) {
+        const claimedControlTask = await claimNextRunnableTask(
           context,
           tasksTable,
           target,
           registry,
           10,
-          ["stopRunner", "stop"],
+          controlLaneTaskNames(),
           runnerIdentity
         );
-        if (claimedStopTask) {
-          runningStopControlPromise = executeClaimedTask(
+        if (claimedControlTask) {
+          runningControlPromise = executeClaimedTask(
             context,
             tasksTable,
             historyTable,
-            claimedStopTask,
+            claimedControlTask,
             registry,
             runningTaskInstances
           ).then(async (outcome) => {
@@ -3410,7 +3702,7 @@ async function runTasksLoop(context, options) {
               await signalRunningTasksStop(context, runningTaskInstances, stopAllowanceMs);
             }
           }).finally(() => {
-            runningStopControlPromise = null;
+            runningControlPromise = null;
           });
         }
       }
@@ -3441,8 +3733,8 @@ async function runTasksLoop(context, options) {
         runningPromises.add(p);
       }
       const wakePromises = [...runningPromises];
-      if (runningStopControlPromise) {
-        wakePromises.push(runningStopControlPromise);
+      if (runningControlPromise) {
+        wakePromises.push(runningControlPromise);
       }
       if (wakePromises.length === 0) {
         await sleepMs(pollMs);
@@ -3661,10 +3953,13 @@ var TasksManager = class _TasksManager {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AbstractTask,
+  LOGGER_RUNTIME_KEYS,
+  LOOP_RUNTIME_KEYS,
   SERVICE_TASK_NAMES,
   TaskGetLogs,
   TaskPing,
   TaskSampleProcess,
+  TaskSetRuntimeParam,
   TaskShellCommand,
   TaskStopRunner,
   TaskSumAB,
@@ -3672,11 +3967,16 @@ var TasksManager = class _TasksManager {
   TasksManager,
   TasksRegistry,
   appendTaskIpcLog,
+  applyRuntimeParam,
+  applyRuntimePatch,
+  coerceRuntimeValue,
+  controlLaneTaskNames,
   convertPattern,
   defaultTasksRegistry,
   enqueueStopTask,
   enqueueTask,
   ensureTaskTables,
+  ensureTasksRuntime,
   flushTaskIpcLogs,
   ipcFileLogsTableNameForSourceResource,
   listAliveRunnerHeartbeats,
@@ -3686,6 +3986,7 @@ var TasksManager = class _TasksManager {
   nextTimeMatch,
   normalizeAllowedTasks,
   queueToTableNames,
+  readLoopRuntime,
   readTaskIpcLogsSnapshot,
   registerInServicesRegistry,
   registerRunnerHeartbeat,