@nmakarov/cli-toolkit 0.47.0 → 0.50.0

package/dist/index.js

@@ -5793,10 +5793,9 @@ function buildEcosystemConfig(service, paths) {
   const outLog = join9(paths.logs, `${pm2.appName}.out.log`);
   const errLog = join9(paths.logs, `${pm2.appName}.err.log`);
   return `/**
- * pm2 ecosystem for ${service.name} \u2014 seeded by cli-toolkit deploy (init).
- *
- * cwd points at the \`current\` symlink (created on first deploy).
- * Tweak \`args\` here, then: pm2 reload ${paths.ecosystem} --update-env
+ * pm2 ecosystem for ${service.name} \u2014 written by cli-toolkit deploy from the
+ * service manifest (init/deploy). Do not hand-edit; change pm2.* in the
+ * manifest and redeploy. cwd \u2192 \`current\` symlink.
  */
 module.exports = {
     apps: [
@@ -5804,7 +5803,7 @@ module.exports = {
             name: "${pm2.appName}",
             script: "${pm2.script}",
             cwd: "${paths.current}",
-            args: "${pm2.args}",
+            args: "${pm2.args ?? ""}",
             instances: 1,
             exec_mode: "fork",
             autorestart: true,
@@ -5843,17 +5842,17 @@ async function initServiceStructure(service, options = {}) {
     if (!dryRun) await mkdir6(dir, { recursive: true });
     created.push(dir);
   }
-  let ecosystemCreated = false;
-  if (await pathExists4(paths.ecosystem)) {
-    skipped.push(paths.ecosystem);
+  const ecosystemExisted = await pathExists4(paths.ecosystem);
+  if (!dryRun) {
+    await writeFile5(paths.ecosystem, buildEcosystemConfig(service, paths), { mode: 420 });
+  }
+  if (ecosystemExisted) {
+    logger.info(`synced ${paths.ecosystem} from manifest`);
   } else {
-    if (!dryRun) {
-      await writeFile5(paths.ecosystem, buildEcosystemConfig(service, paths), { mode: 420 });
-    }
-    ecosystemCreated = true;
     created.push(paths.ecosystem);
+    logger.info(`seeded ${paths.ecosystem}`);
   }
-  const line = `[${(/* @__PURE__ */ new Date()).toISOString()}] init-structure service=${service.name} dryRun=${dryRun} created=${created.length} skipped=${skipped.length}
+  const line = `[${(/* @__PURE__ */ new Date()).toISOString()}] init-structure service=${service.name} dryRun=${dryRun} created=${created.length} skipped=${skipped.length} ecosystem=synced
 `;
   if (!dryRun) {
     await mkdir6(paths.logs, { recursive: true });
@@ -5862,8 +5861,7 @@ async function initServiceStructure(service, options = {}) {
   logger.info(`service=${service.name} appsRoot=${paths.root}`);
   logger.info(`created: ${created.length ? created.join(", ") : "(none)"}`);
   logger.info(`already present: ${skipped.length ? skipped.join(", ") : "(none)"}`);
-  if (ecosystemCreated) logger.info(`seeded ${paths.ecosystem}`);
-  return { paths, created, skipped, ecosystemCreated };
+  return { paths, created, skipped, ecosystemCreated: !ecosystemExisted, ecosystemSynced: true };
 }
 
 // src/deploy/bootstrap-host.js
@@ -5960,11 +5958,55 @@ async function installLogrotate(service, options = {}) {
   await runShell(`sudo cp '${tmp}' '${conf}'`, { logger });
   logger.info(`logrotate config written: ${conf}`);
 }
+var OPERATOR_SHELL_BEGIN = "# >>> mlsfarm-operator >>>";
+var OPERATOR_SHELL_END = "# <<< mlsfarm-operator <<<";
+async function installOperatorShell(service, options = {}) {
+  const { user = "ubuntu", dryRun = false, logger = console } = options;
+  const appsRoot = service.appsRoot;
+  if (!appsRoot) {
+    logger.warn("installOperatorShell: service.appsRoot missing \u2014 skipped");
+    return;
+  }
+  const home = user === "ubuntu" || user === process.env.USER ? join10(homedir(), ".bashrc") : `/home/${user}/.bashrc`;
+  const currentDir = join10(appsRoot, "current");
+  const block = [
+    OPERATOR_SHELL_BEGIN,
+    "# Managed by cli-toolkit deploy bootstrap \u2014 do not edit by hand.",
+    "export ENV=production",
+    `if [ -d "${currentDir}" ]; then`,
+    `  cd "${currentDir}" || true`,
+    "fi",
+    OPERATOR_SHELL_END,
+    ""
+  ].join("\n");
+  if (dryRun) {
+    logger.info(`[dryRun] would update ${home} (ENV=production, cd ${currentDir})`);
+    return;
+  }
+  let existing = "";
+  if (await pathExists5(home)) {
+    existing = await readFile4(home, "utf8");
+  }
+  const begin = existing.indexOf(OPERATOR_SHELL_BEGIN);
+  const end = existing.indexOf(OPERATOR_SHELL_END);
+  let next;
+  if (begin !== -1 && end !== -1 && end > begin) {
+    const afterEnd = end + OPERATOR_SHELL_END.length;
+    const rest = existing.slice(afterEnd).replace(/^\n/, "");
+    next = `${existing.slice(0, begin).replace(/\s*$/, "\n")}${block}${rest}`;
+  } else {
+    next = `${existing.replace(/\s*$/, "\n")}
+${block}`;
+  }
+  await writeFile6(home, next, { mode: 420 });
+  logger.info(`operator shell: ${home} \u2192 ENV=production, cd ${currentDir}`);
+}
 async function bootstrapHost(service, options = {}) {
   const { deployKey = service.deployKey, user = "ubuntu", dryRun = false, logger = console } = options;
   await ensurePm2Startup({ user, dryRun, logger });
   if (deployKey) await installDeployKey(deployKey, { dryRun, logger });
   await installLogrotate(service, { dryRun, logger });
+  await installOperatorShell(service, { user, dryRun, logger });
   logger.info("bootstrap-host complete");
 }
 
@@ -7754,6 +7796,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 {
   /**
@@ -7772,7 +8081,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.
@@ -7878,7 +8187,9 @@ var SERVICE_TASK_NAMES = [
   "shellCommand",
   "systemInfo",
   "info",
-  "getLogs"
+  "getLogs",
+  "setRuntimeParam",
+  "setRunnerParam"
 ];
 function normalizeAllowedTasks(value) {
   if (!value) return void 0;
@@ -8305,18 +8616,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;
@@ -8327,9 +8643,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,
@@ -8342,6 +8665,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(),
@@ -8355,22 +8679,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) => {
@@ -8381,7 +8706,7 @@ async function runTasksLoop(context, options) {
               await signalRunningTasksStop(context, runningTaskInstances, stopAllowanceMs);
             }
           }).finally(() => {
-            runningStopControlPromise = null;
+            runningControlPromise = null;
           });
         }
       }
@@ -8412,8 +8737,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);
@@ -8641,6 +8966,8 @@ export {
   FooterPresets,
   GridCell,
   InputField,
+  LOGGER_RUNTIME_KEYS,
+  LOOP_RUNTIME_KEYS,
   ListComponent,
   ListItem,
   MultiColumnListComponent,
@@ -8659,6 +8986,7 @@ export {
   TaskGetLogs,
   TaskPing,
   TaskSampleProcess,
+  TaskSetRuntimeParam,
   TaskShellCommand,
   TaskStopRunner,
   TaskSumAB,
@@ -8670,12 +8998,16 @@ export {
   activateRelease,
   appendDeployLog,
   appendTaskIpcLog,
+  applyRuntimeParam,
+  applyRuntimePatch,
   bootstrapHost,
   buildBreadcrumb,
   buildDetailBreadcrumb,
   buildFooter,
   bumpPatchVersion,
   cloneRepo,
+  coerceRuntimeValue,
+  controlLaneTaskNames,
   convertPattern,
   createRelease,
   defaultFileSynopsisFunction,
@@ -8697,11 +9029,13 @@ export {
   ensureSchemaEverywhere,
   ensureTable,
   ensureTaskTables,
+  ensureTasksRuntime,
   flushTaskIpcLogs,
   getArgsInstance,
   createElement2 as h,
   initServiceStructure,
   installDeps,
+  installOperatorShell,
   ipcFileLogsTableNameForSourceResource,
   joiEdateType,
   joiStringArrayType,
@@ -8727,6 +9061,7 @@ export {
   pullRepo,
   queueToTableNames,
   readCurrentRelease,
+  readLoopRuntime,
   readReleaseBuildInfo,
   readTaskIpcLogsSnapshot,
   registerInServicesRegistry,