@nmakarov/cli-toolkit 0.49.0 → 0.50.0

package/dist/cli-runner.js

@@ -3969,6 +3969,51 @@ async function dropLegacyTaskNameColumn(db, tableNames, { dryRun, log, label })
   }
   return actions;
 }
+async function enqueueTask(context, options) {
+  const db = getDb(context);
+  const queueName = options.queueName ?? "tasks";
+  const { tasksTable } = queueToTableNames(queueName);
+  const id = randomUUID();
+  const name = options.name ?? options.task;
+  if (!name) {
+    throw new Error("enqueueTask: name (or task) is required");
+  }
+  const schedule = options.schedule?.trim() ? options.schedule : null;
+  let nextRunAt = null;
+  if (options.nextRunAt !== void 0) {
+    nextRunAt = options.nextRunAt == null ? null : new Date(options.nextRunAt);
+  } else if (schedule) {
+    nextRunAt = nextTimeMatch(schedule, /* @__PURE__ */ new Date());
+  }
+  const row = {
+    id,
+    name,
+    params: toJsonColumn(options.params ?? null),
+    opid: options.opid ?? null,
+    priority: options.priority ?? 50,
+    schedule,
+    next_run_at: nextRunAt,
+    service_group: options.serviceGroup ?? null,
+    instance_number: options.instanceNumber ?? null,
+    service_name: options.serviceName ?? null,
+    server_name: options.serverName ?? null,
+    status: "idle",
+    status_changed_at: db.fn.now()
+  };
+  if (await tableHasLegacyTaskColumn(db, tasksTable)) {
+    row.task = name;
+  }
+  await db(tasksTable).insert(row);
+  return id;
+}
+var legacyTaskColumnCache = /* @__PURE__ */ new Map();
+async function tableHasLegacyTaskColumn(db, tableName) {
+  const key = `${db?.config?.name ?? "db"}:${tableName}`;
+  if (!legacyTaskColumnCache.has(key)) {
+    legacyTaskColumnCache.set(key, await db.schema.hasColumn(tableName, "task"));
+  }
+  return legacyTaskColumnCache.get(key);
+}
 async function updateTaskProgress(context, tasksTable, taskId, progress) {
   const db = getDb(context);
   await db(tasksTable).where({ id: taskId }).update({
@@ -3984,6 +4029,19 @@ function getDb2(context) {
   }
   return db;
 }
+function parseMetadataColumn(value) {
+  if (!value) return {};
+  if (typeof value === "object" && !Array.isArray(value)) return value;
+  if (typeof value === "string") {
+    try {
+      const p = JSON.parse(value);
+      return p && typeof p === "object" && !Array.isArray(value) ? p : {};
+    } catch {
+      return {};
+    }
+  }
+  return {};
+}
 var DEFAULT_GROUP_MAX_INSTANCES = {
   intake: 1,
   harvest: 1,
@@ -4182,11 +4240,33 @@ async function touchServicesRegistry(context, registration) {
     pid
   });
 }
+async function updateServicesRegistryMetadata(context, registration, patch) {
+  const db = getDb2(context);
+  const row = await db(registration.registryTable).where({ id: registration.rowId }).first();
+  const prev = parseMetadataColumn(row?.metadata);
+  const merged = { ...prev, ...patch };
+  await db(registration.registryTable).where({ id: registration.rowId }).update({
+    metadata: toJsonColumn(merged),
+    last_seen_at: db.fn.now()
+  });
+  context.logger.info?.(`[services-registry] metadata updated for ${registration.serviceName}`);
+}
 async function unregisterServicesRegistry(context, registration) {
   const db = getDb2(context);
   await db(registration.registryTable).where({ id: registration.rowId }).delete();
   context.logger.info?.(`[services-registry] unregistered name=${registration.serviceName} id=${registration.rowId}`);
 }
+async function listServicesRegistry(context, options = { queueName: "tasks" }) {
+  const db = getDb2(context);
+  const staleMs = options.staleMs ?? 6e4;
+  const cutoff = new Date(Date.now() - staleMs);
+  const table = queueToTableNames(options.queueName).registryTable;
+  let q = db(table).where("last_seen_at", ">", cutoff).orderBy([{ column: "service_group", order: "asc" }, { column: "service_name", order: "asc" }]);
+  if (options.serviceGroup?.trim()) {
+    q = q.where({ service_group: options.serviceGroup.trim() });
+  }
+  return await q;
+}
 
 // src/tasks/taskLogs.js
 import path4 from "path";
@@ -6145,6 +6225,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 {
   /**
@@ -6163,7 +6510,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.
@@ -6492,18 +6839,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;
@@ -6514,9 +6866,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,
@@ -6529,6 +6888,7 @@ async function runTasksLoop(context, options) {
       enforceMaxInstances: options.runnerEnforceMaxInstances ?? true,
       metadata: options.runnerMetadata ?? defaultMeta
     });
+    context.servicesRegistry = registryReg;
     runnerIdentity = {
       service_name: registryReg.serviceName,
       server_name: os3.hostname(),
@@ -6542,22 +6902,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) => {
@@ -6568,7 +6929,7 @@ async function runTasksLoop(context, options) {
               await signalRunningTasksStop(context, runningTaskInstances, stopAllowanceMs);
             }
           }).finally(() => {
-            runningStopControlPromise = null;
+            runningControlPromise = null;
           });
         }
       }
@@ -6599,8 +6960,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);