easy-devops 1.3.4 → 1.3.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,158 @@
1
+ /**
2
+ * core/dashboardProcess.js
3
+ *
4
+ * Starting, stopping and locating the detached dashboard process.
5
+ *
6
+ * Lifted out of cli/menus/dashboard.js so the CLI and the update worker share
7
+ * one implementation. The worker runs after the dashboard it is replacing has
8
+ * been killed and must start the NEW code back up on the same port — a second
9
+ * copy of this logic would be exactly the kind of drift that took the update
10
+ * menu down.
11
+ *
12
+ * The dashboard is a plain detached `node src/dashboard/server.js`; the
13
+ * background service runs the daemon, not this. Its pid and port live in the
14
+ * SQLite settings table so any later process can find it.
15
+ */
16
+
17
+ import { createServer } from 'net';
18
+ import { spawn } from 'child_process';
19
+ import { openSync, closeSync, writeSync } from 'fs';
20
+ import fs from 'fs/promises';
21
+ import http from 'http';
22
+ import path from 'path';
23
+ import { fileURLToPath } from 'url';
24
+ import { loadConfig } from './config.js';
25
+ import { dbGet, dbSet } from './db.js';
26
+ import { getDataDir } from './platform.js';
27
+ import { run } from './shell.js';
28
+
29
+ const __dirname = path.dirname(fileURLToPath(import.meta.url));
30
+ const isWindows = process.platform === 'win32';
31
+
32
+ // Principle IV: logs live in the user's data directory, never inside the
33
+ // package — a package-relative path is wiped by `npm update`. Follows
34
+ // EASY_DEVOPS_DATA_DIR in dev mode like the database and sessions do.
35
+ export const DASHBOARD_LOG_PATH = path.join(getDataDir(), 'logs', 'dashboard.log');
36
+ const SERVER_PATH = path.resolve(__dirname, '..', 'dashboard', 'server.js');
37
+
38
+ // ─── Port helpers ─────────────────────────────────────────────────────────────
39
+
40
+ function isPortFree(port) {
41
+ return new Promise((resolve) => {
42
+ const srv = createServer();
43
+ srv.once('error', () => resolve(false));
44
+ srv.once('listening', () => srv.close(() => resolve(true)));
45
+ srv.listen(port, '127.0.0.1');
46
+ });
47
+ }
48
+
49
+ export async function findFreePort(startPort) {
50
+ let port = startPort;
51
+ while (!(await isPortFree(port))) {
52
+ port++;
53
+ if (port > 65535) throw new Error('No free port found');
54
+ }
55
+ return port;
56
+ }
57
+
58
+ // ─── HTTP ping — the reliable way to know Express is actually up ─────────────
59
+
60
+ function httpPing(port, timeoutMs = 2000) {
61
+ return new Promise((resolve) => {
62
+ const req = http.get(`http://localhost:${port}/`, (res) => {
63
+ res.destroy();
64
+ resolve(true);
65
+ });
66
+ req.on('error', () => resolve(false));
67
+ req.setTimeout(timeoutMs, () => { req.destroy(); resolve(false); });
68
+ });
69
+ }
70
+
71
+ /** Polls every 500 ms until Express answers or the deadline passes. */
72
+ export async function waitForServer(port, maxWaitMs = 8000) {
73
+ const deadline = Date.now() + maxWaitMs;
74
+ while (Date.now() < deadline) {
75
+ if (await httpPing(port, 1000)) return true;
76
+ await new Promise((r) => setTimeout(r, 500));
77
+ }
78
+ return false;
79
+ }
80
+
81
+ // ─── Status ───────────────────────────────────────────────────────────────────
82
+
83
+ export function isPidAlive(pid) {
84
+ if (!pid) return false;
85
+ try { process.kill(pid, 0); return true; } catch { return false; }
86
+ }
87
+
88
+ export async function getDashboardStatus() {
89
+ const { dashboardPort } = loadConfig();
90
+ const storedPid = dbGet('dashboard-pid');
91
+ const storedPort = dbGet('dashboard-port') ?? dashboardPort;
92
+ const pidAlive = isPidAlive(storedPid);
93
+ const responding = pidAlive && await httpPing(storedPort, 1000);
94
+
95
+ if (storedPid && !responding) {
96
+ dbSet('dashboard-pid', null);
97
+ dbSet('dashboard-port', null);
98
+ }
99
+
100
+ return {
101
+ running: responding,
102
+ port: storedPort,
103
+ configPort: dashboardPort,
104
+ pid: responding ? storedPid : null,
105
+ };
106
+ }
107
+
108
+ // ─── Start / stop ─────────────────────────────────────────────────────────────
109
+
110
+ /**
111
+ * Starts the dashboard detached, logging to <dataDir>/logs/dashboard.log.
112
+ *
113
+ * `env` is merged over the current process's environment; the update worker
114
+ * passes EASY_DEVOPS_DATA_DIR so the new dashboard runs on the same data as
115
+ * the one it replaces.
116
+ *
117
+ * @param {number} port
118
+ * @param {Object} [opts]
119
+ * @param {Object} [opts.env]
120
+ * @returns {Promise<{ success: boolean, pid: number, port: number, logPath: string }>}
121
+ */
122
+ export async function startDashboard(port, { env = {} } = {}) {
123
+ await fs.mkdir(path.dirname(DASHBOARD_LOG_PATH), { recursive: true });
124
+
125
+ // openSync gives a real fd immediately — required by spawn's stdio option
126
+ const logFd = openSync(DASHBOARD_LOG_PATH, 'a');
127
+ writeSync(logFd, `\n--- dashboard start ${new Date().toISOString()} port=${port} ---\n`);
128
+
129
+ const child = spawn(process.execPath, [SERVER_PATH], {
130
+ detached: true,
131
+ stdio: ['ignore', logFd, logFd],
132
+ windowsHide: true,
133
+ env: { ...process.env, ...env, DASHBOARD_PORT: String(port) },
134
+ });
135
+ child.unref();
136
+ // Parent closes its copy of the fd; the child keeps its own inherited copy
137
+ closeSync(logFd);
138
+
139
+ dbSet('dashboard-pid', child.pid);
140
+ dbSet('dashboard-port', port);
141
+
142
+ const up = await waitForServer(port, 8000);
143
+ return { success: up, pid: child.pid, port, logPath: DASHBOARD_LOG_PATH };
144
+ }
145
+
146
+ export async function stopDashboard(pid) {
147
+ if (!pid) return { success: false };
148
+ try {
149
+ if (isWindows) {
150
+ await run(`taskkill /PID ${pid} /F`);
151
+ } else {
152
+ process.kill(pid, 'SIGTERM');
153
+ }
154
+ } catch { /* already gone */ }
155
+ dbSet('dashboard-pid', null);
156
+ dbSet('dashboard-port', null);
157
+ return { success: true };
158
+ }
@@ -63,8 +63,24 @@ let agentState = {
63
63
  attempts: 0,
64
64
  };
65
65
 
66
- function setState(status, lastError = null) {
67
- agentState = { ...agentState, status, lastError };
66
+ function setState(status, lastError = null, attempts = agentState.attempts) {
67
+ agentState = { ...agentState, status, lastError, attempts };
68
+ publishAgentState();
69
+ }
70
+
71
+ /**
72
+ * Puts the agent's state on the job bus, so a dashboard in another process can
73
+ * report it.
74
+ *
75
+ * The agent runs in the process that owns the jobs, which is often the daemon.
76
+ * The dashboard's status endpoint used to read its own (empty) agent state and
77
+ * sat on "Connecting…" for ever. Publishing on every transition means the
78
+ * daemon's IPC channel carries the answer, and the dashboard's view follows.
79
+ */
80
+ function publishAgentState() {
81
+ try {
82
+ publish('hub:agentState', getHubAgentStatus());
83
+ } catch { /* a status listener must never break the connection */ }
68
84
  }
69
85
 
70
86
  // ─── CPU usage helper ──────────────────────────────────────────────────────────
@@ -203,8 +219,8 @@ async function pushServiceState() {
203
219
  * Reports the PM2 process list, as read-only telemetry.
204
220
  *
205
221
  * Monitoring is never gated in this project's permission catalog — a paired
206
- * server is a monitored server. Acting on a process from the Hub is a separate
207
- * matter and is still `comingSoon` in the tree (process.start/stop/restart).
222
+ * server is a monitored server. Acting on a process is a separate matter and
223
+ * needs process.start / process.stop / process.restart (hub:manageProcess).
208
224
  *
209
225
  * Skipped entirely when the PM2 daemon is not running, so that reporting never
210
226
  * starts one.
@@ -481,6 +497,60 @@ async function handleDeployHook(payload) {
481
497
  });
482
498
  }
483
499
 
500
+ /**
501
+ * Starts, stops or restarts one PM2 process, mirroring the dashboard's own
502
+ * processes controller.
503
+ *
504
+ * The checks are the same ones, in the same order, and they are deliberately
505
+ * repeated here rather than trusted from the Hub: the Hub's copy of the
506
+ * permission map is a hint, and its process list is whatever the agent last
507
+ * pushed. The agent is the only place that sees the real PM2 state of this
508
+ * machine.
509
+ */
510
+ const PROCESS_ACTIONS = {
511
+ // PM2 "start" for an app that exists is a restart.
512
+ start: runner.restart,
513
+ restart: runner.restart,
514
+ stop: runner.stop,
515
+ };
516
+
517
+ async function handleManageProcess(payload) {
518
+ return runCommand('hub:manageProcess', payload, async ({ action, name }) => {
519
+ const fn = PROCESS_ACTIONS[action];
520
+ if (!fn) throw new Error(`Unknown process action: ${action}`);
521
+ if (typeof name !== 'string' || !name.trim()) throw new Error('A process name is required');
522
+ if (name.length > 200) throw new Error('That process name is too long');
523
+
524
+ const pm2 = await runner.detect();
525
+ if (!pm2.installed) throw new Error('PM2 is not installed on this server');
526
+ const pm2Path = pm2.path ?? 'pm2';
527
+
528
+ // Only act on something PM2 actually knows, so a typo cannot be reported
529
+ // as a success.
530
+ const listed = await runner.list({ pm2Path });
531
+ if (!listed.ok) throw new Error(listed.error || 'Could not read the PM2 process list');
532
+ const app = listed.apps.find((a) => a.name === name);
533
+ if (!app) throw new Error(`PM2 has no process named "${name}"`);
534
+
535
+ // PM2 keeps one process list per OS user; another account's app may be
536
+ // visible but cannot be controlled from this process.
537
+ if (app.user && app.user !== runner.currentUser()) {
538
+ throw new Error(
539
+ `"${name}" belongs to OS user "${app.user}", not "${runner.currentUser()}". `
540
+ + 'PM2 keeps a separate process list per user. Sign in as that user to control it.',
541
+ );
542
+ }
543
+
544
+ const result = await fn(name, { pm2Path });
545
+ if (!result.ok) throw new Error(result.output || `pm2 ${action} failed`);
546
+
547
+ // The Hub's process table is fed by this push; without it the row would
548
+ // keep showing the old status until the next 60-second heartbeat.
549
+ pushProcesses();
550
+ return { name, action, managed: Boolean(app.managed), output: result.output ?? '' };
551
+ });
552
+ }
553
+
484
554
  // ─── Permission + revision sync ───────────────────────────────────────────────
485
555
 
486
556
  /**
@@ -595,8 +665,7 @@ function cancelRejoin() {
595
665
  export function initHubAgent() {
596
666
  const link = getHubLink();
597
667
  if (!link) {
598
- setState(HUB_AGENT_STATUS.NOT_LINKED);
599
- agentState.attempts = 0;
668
+ setState(HUB_AGENT_STATUS.NOT_LINKED, null, 0);
600
669
  return;
601
670
  }
602
671
 
@@ -625,7 +694,7 @@ export function initHubAgent() {
625
694
  activeLink = linkSignature(link);
626
695
 
627
696
  cancelRejoin();
628
- agentState = { status: HUB_AGENT_STATUS.CONNECTING, lastError: null, attempts: 0 };
697
+ setState(HUB_AGENT_STATUS.CONNECTING, null, 0);
629
698
 
630
699
  // Bind handlers to this specific instance. Re-pairing replaces `socket`, and
631
700
  // a late event from a discarded instance must not mutate the new one's state.
@@ -644,7 +713,7 @@ export function initHubAgent() {
644
713
  if (!isCurrent()) return;
645
714
  console.log('[hubAgent] Connected to hub');
646
715
  cancelRejoin();
647
- agentState = { status: HUB_AGENT_STATUS.CONNECTED, lastError: null, attempts: 0 };
716
+ setState(HUB_AGENT_STATUS.CONNECTED, null, 0);
648
717
  // Push server metadata so the hub can tailor the domain form (SSL paths, etc.)
649
718
  const { sslDir } = loadConfig();
650
719
  self.emit('server:info', { platform: platformName, sslDir: sslDir ?? '' });
@@ -712,11 +781,11 @@ export function initHubAgent() {
712
781
  if (!self.active) scheduleRejoin();
713
782
 
714
783
  // Transport/network failure — socket.io keeps retrying with backoff.
715
- agentState = {
716
- status: HUB_AGENT_STATUS.UNREACHABLE,
717
- lastError: `Cannot reach the hub (${message}). Retrying...`,
718
- attempts: agentState.attempts + 1,
719
- };
784
+ setState(
785
+ HUB_AGENT_STATUS.UNREACHABLE,
786
+ `Cannot reach the hub (${message}). Retrying...`,
787
+ agentState.attempts + 1,
788
+ );
720
789
  console.error('[hubAgent] Connection error:', message);
721
790
  });
722
791
 
@@ -729,6 +798,7 @@ export function initHubAgent() {
729
798
  self.on('hub:getLogs', handleGetLogs);
730
799
  self.on('hub:manageDeploy', handleManageDeploy);
731
800
  self.on('hub:deployHook', handleDeployHook);
801
+ self.on('hub:manageProcess', handleManageProcess);
732
802
  }
733
803
 
734
804
  /**
@@ -806,8 +876,7 @@ export function stopHubAgent() {
806
876
  socket.disconnect();
807
877
  socket = null;
808
878
  }
809
- setState(HUB_AGENT_STATUS.NOT_LINKED);
810
- agentState.attempts = 0;
879
+ setState(HUB_AGENT_STATUS.NOT_LINKED, null, 0);
811
880
  }
812
881
 
813
882
  /**
@@ -96,25 +96,22 @@ export const PERMISSION_TREE = Object.freeze([
96
96
  {
97
97
  id: 'process',
98
98
  label: 'Processes',
99
- description: 'Control the PM2 processes on this server, including the Easy DevOps service itself.',
99
+ description: 'Control the PM2 processes on this server. Easy DevOps itself runs as a background service, not a PM2 app, so it cannot be controlled from here.',
100
100
  children: [
101
101
  {
102
102
  id: 'process.start',
103
103
  label: 'Start',
104
104
  description: 'Start a stopped PM2 process from the Hub.',
105
- comingSoon: true,
106
105
  },
107
106
  {
108
107
  id: 'process.stop',
109
108
  label: 'Stop',
110
- description: 'Stop a running PM2 process from the Hub. Stopping the dashboard would cut the Hub off from this server.',
111
- comingSoon: true,
109
+ description: 'Stop a running PM2 process from the Hub.',
112
110
  },
113
111
  {
114
112
  id: 'process.restart',
115
113
  label: 'Restart',
116
114
  description: 'Restart a PM2 process from the Hub.',
117
- comingSoon: true,
118
115
  },
119
116
  ],
120
117
  },
@@ -310,6 +307,13 @@ export function migrateLegacyPermissions(stored) {
310
307
 
311
308
  // ─── Command → permission mapping ─────────────────────────────────────────────
312
309
 
310
+ /** Own-key lookup: `map['constructor']` would otherwise hit the prototype. */
311
+ function fromMap(map, action) {
312
+ return typeof action === 'string' && Object.prototype.hasOwnProperty.call(map, action)
313
+ ? map[action]
314
+ : undefined;
315
+ }
316
+
313
317
  /**
314
318
  * Resolves the permission a hub command payload requires.
315
319
  *
@@ -334,7 +338,7 @@ export function permissionForCommand(command, payload = {}) {
334
338
  reload: 'nginx.reload',
335
339
  test: 'nginx.test',
336
340
  };
337
- return map[payload?.action] ?? undefined;
341
+ return fromMap(map, payload?.action);
338
342
  }
339
343
 
340
344
  case 'hub:manageDomain': {
@@ -345,7 +349,7 @@ export function permissionForCommand(command, payload = {}) {
345
349
  delete: 'domains.delete',
346
350
  reload: 'nginx.reload',
347
351
  };
348
- return map[payload?.action] ?? undefined;
352
+ return fromMap(map, payload?.action);
349
353
  }
350
354
 
351
355
  case 'hub:manageSSL': {
@@ -355,7 +359,18 @@ export function permissionForCommand(command, payload = {}) {
355
359
  issue: 'ssl.issue',
356
360
  delete: 'ssl.delete',
357
361
  };
358
- return map[payload?.action] ?? undefined;
362
+ return fromMap(map, payload?.action);
363
+ }
364
+
365
+ case 'hub:manageProcess': {
366
+ const map = {
367
+ // PM2 "start" on an existing app is a restart, exactly as in the
368
+ // dashboard's own processes controller.
369
+ start: 'process.start',
370
+ stop: 'process.stop',
371
+ restart: 'process.restart',
372
+ };
373
+ return fromMap(map, payload?.action);
359
374
  }
360
375
 
361
376
  case 'hub:manageDeploy': {
@@ -380,7 +395,7 @@ export function permissionForCommand(command, payload = {}) {
380
395
  setEnv: 'deploy.env',
381
396
  };
382
397
  const action = payload?.action;
383
- return Object.prototype.hasOwnProperty.call(map, action) ? map[action] : undefined;
398
+ return fromMap(map, action);
384
399
  }
385
400
 
386
401
  // Not dispatchable by a Hub user: only the Hub's CI endpoint sends it, and
@@ -47,6 +47,11 @@ export const JOB_EVENTS = Object.freeze([
47
47
  'notification:new',
48
48
  'local:changed',
49
49
  'service:changed',
50
+ // The Hub agent lives in whichever process owns the jobs. A dashboard in
51
+ // another process reads its state from the daemon's IPC channel, so every
52
+ // transition has to travel: without this event the dashboard only ever saw
53
+ // the hello snapshot and reported "Connecting…" for ever.
54
+ 'hub:agentState',
50
55
  ]);
51
56
 
52
57
  /**
@@ -0,0 +1,115 @@
1
+ /**
2
+ * core/updateStatus.js
3
+ *
4
+ * The single record of an update the dashboard asked for.
5
+ *
6
+ * The process that starts an update does not survive it, so memory cannot be
7
+ * the medium: the HTTP handler writes the first record, the detached worker
8
+ * rewrites it at every phase, and the dashboard that comes back reads it to
9
+ * tell the user what happened. A crash needs no separate handling — an active
10
+ * phase whose worker is gone and whose heartbeat stopped is reported as
11
+ * interrupted, never as still running.
12
+ */
13
+
14
+ import fs from 'fs';
15
+ import path from 'path';
16
+ import { getDataDir } from './platform.js';
17
+ import { isPidAlive } from './daemon/lock.js';
18
+
19
+ const STATUS_FILE = 'update-status.json';
20
+
21
+ /** Phases that mean "a run has not finished". */
22
+ export const ACTIVE_PHASES = Object.freeze(['starting', 'stopping', 'updating', 'restarting']);
23
+
24
+ /** Phases that are a final outcome. */
25
+ export const FINAL_PHASES = Object.freeze(['done', 'failed', 'interrupted']);
26
+
27
+ /**
28
+ * How old the heartbeat may be before an active run is called interrupted.
29
+ * Generous: the npm install step legitimately runs for minutes, and its worker
30
+ * only needs to refresh every few seconds.
31
+ */
32
+ export const STALE_AFTER_MS = 45_000;
33
+
34
+ /** @returns {string} Absolute path to the status file. */
35
+ export function statusPath(dataDir = getDataDir()) {
36
+ return path.join(dataDir, STATUS_FILE);
37
+ }
38
+
39
+ /**
40
+ * The last written run, or null.
41
+ *
42
+ * @param {string} [dataDir]
43
+ * @returns {Object|null}
44
+ */
45
+ export function readStatus(dataDir = getDataDir()) {
46
+ try {
47
+ const parsed = JSON.parse(fs.readFileSync(statusPath(dataDir), 'utf8'));
48
+ if (!parsed || typeof parsed !== 'object') return null;
49
+ if (typeof parsed.id !== 'string' || typeof parsed.phase !== 'string') return null;
50
+ return parsed;
51
+ } catch {
52
+ // Missing, unreadable or truncated: all mean "no run to report". A
53
+ // half-written file is possible after a crash mid-write and is not data.
54
+ return null;
55
+ }
56
+ }
57
+
58
+ /**
59
+ * Merges a patch into the status file and stamps the heartbeat.
60
+ *
61
+ * Atomic (temp + rename), because the dashboard that reads it may be starting
62
+ * at the same moment the worker writes the final record.
63
+ *
64
+ * @param {Object} patch
65
+ * @param {Object} [opts]
66
+ * @param {string} [opts.dataDir]
67
+ * @param {boolean} [opts.replace] Start a fresh record instead of merging
68
+ * @returns {Object} The record as written
69
+ */
70
+ export function writeStatus(patch, { dataDir = getDataDir(), replace = false } = {}) {
71
+ const current = replace ? {} : readStatus(dataDir) ?? {};
72
+ const next = { ...current, ...patch, updatedAt: Date.now() };
73
+
74
+ const target = statusPath(dataDir);
75
+ const temp = `${target}.${process.pid}.tmp`;
76
+
77
+ fs.mkdirSync(path.dirname(target), { recursive: true });
78
+ fs.writeFileSync(temp, `${JSON.stringify(next, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
79
+ fs.renameSync(temp, target);
80
+
81
+ return next;
82
+ }
83
+
84
+ /**
85
+ * True while a run should be shown as in progress.
86
+ *
87
+ * A live worker pid is proof enough; without one (the spawn has not reported
88
+ * back yet), a fresh heartbeat is. Both stale means the worker died and the
89
+ * run will never finish on its own.
90
+ *
91
+ * @param {Object|null} run
92
+ * @param {Object} [opts]
93
+ * @returns {boolean}
94
+ */
95
+ export function runIsActive(run, { now = Date.now(), isAlive = isPidAlive } = {}) {
96
+ if (!run || !ACTIVE_PHASES.includes(run.phase)) return false;
97
+ if (run.workerPid && isAlive(run.workerPid)) return true;
98
+ return now - Number(run.updatedAt ?? 0) < STALE_AFTER_MS;
99
+ }
100
+
101
+ /**
102
+ * The run as an API should present it: an abandoned active phase becomes
103
+ * `interrupted`, so no client has to reason about heartbeats.
104
+ *
105
+ * @param {Object|null} run
106
+ * @param {Object} [opts]
107
+ * @returns {Object|null}
108
+ */
109
+ export function describeRun(run, opts) {
110
+ if (!run) return null;
111
+ if (ACTIVE_PHASES.includes(run.phase) && !runIsActive(run, opts)) {
112
+ return { ...run, phase: 'interrupted' };
113
+ }
114
+ return run;
115
+ }
@@ -3,23 +3,25 @@
3
3
  *
4
4
  * Updating Easy DevOps itself.
5
5
  *
6
- * ── Why this is not a dashboard feature, and not a Hub command ─────────────
6
+ * ── Why the request cannot do the work ────────────────────────────────────
7
7
  *
8
- * The process that would perform the update is the process being replaced.
9
- * `npm install -g` overwrites the package directory the dashboard is running
10
- * from, and the background service has to be stopped so the files it holds
11
- * open can be replaced — on Windows an open handle makes the install fail
12
- * outright. A request that arrives over HTTP or over the Hub socket cannot
13
- * survive its own server being stopped, so it could report neither success nor
14
- * failure: the connection would simply end mid-update, and whatever happened
15
- * next would be invisible.
8
+ * npm replaces the files the caller is running from, and the background
9
+ * service has to be stopped so those files can be replaced — on Windows an
10
+ * open handle makes the install fail outright. A request that arrives over
11
+ * HTTP or over the Hub socket cannot survive its own server being stopped, so
12
+ * it could report neither success nor failure: the connection would simply
13
+ * end mid-update, and whatever happened next would be invisible.
16
14
  *
17
- * Doing it from a terminal means someone is watching, the output is visible,
18
- * and a failure can be rolled back while they are still there. That is not a
19
- * limitation to be engineered around; it is the correct shape for an operation
20
- * that replaces the running code. A later design could hand the work to a
21
- * short-lived detached helper that reports back afterwards — until then, the
22
- * CLI is the honest answer and the output says so.
15
+ * So the work is owned by a caller that outlives it:
16
+ *
17
+ * - `ezz update` runs it in a terminal, where someone is watching and a
18
+ * failure can be rolled back while they are still there;
19
+ * - Settings > Update in the dashboard records the run and hands it to a
20
+ * detached worker (dashboard/updateWorker.js) that survives the restart,
21
+ * performs THIS flow, starts the dashboard again, and leaves the outcome
22
+ * in core/updateStatus.js for the new dashboard to read.
23
+ *
24
+ * The Hub has neither, which is what whyCliOnly() explains.
23
25
  *
24
26
  * ── Why the install source is detected first ───────────────────────────────
25
27
  *
@@ -272,19 +274,20 @@ function trim(result) {
272
274
  }
273
275
 
274
276
  /**
275
- * The lines explaining why this is a terminal-only operation.
277
+ * The lines explaining why the Hub cannot run an update.
276
278
  *
277
- * Printed by `ezz update` on every run, successful or not: the question "why
278
- * can't I do this from the dashboard?" is asked once per user, and the answer
279
- * belongs where they are already looking.
279
+ * Printed by `ezz update` on every run: the question "why can't I do this from
280
+ * the Hub?" is asked once per user, and the answer belongs where they are
281
+ * already looking. The dashboard CAN do it (Settings > Update, via the
282
+ * detached worker), so the lines say so rather than claiming otherwise.
280
283
  *
281
284
  * @returns {string[]}
282
285
  */
283
286
  export function whyCliOnly() {
284
287
  return [
285
- 'Updating from the dashboard or the Hub is not possible yet:',
286
- 'the process that performs the update is the one being replaced and',
287
- 'stopped, so it could not report what happened. A terminal can.',
288
+ 'The Hub cannot run this: the process performing the update is being',
289
+ 'replaced and stopped, so it could not report back. Use Settings > Update',
290
+ 'in the dashboard, or `ezz update` in a terminal - same flow either way.',
288
291
  ];
289
292
  }
290
293