easy-devops 1.3.6 → 1.4.0

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.
Files changed (69) hide show
  1. package/README.md +1 -0
  2. package/dist/ui/assets/index-Bu7af-Kj.css +1 -0
  3. package/dist/ui/assets/index-gndgYe3K.js +532 -0
  4. package/dist/ui/assets/socket-Bv0wCEgi.js +65 -0
  5. package/dist/ui/index.html +2 -2
  6. package/package.json +2 -2
  7. package/src/cli/index.js +8 -0
  8. package/src/cli/managers/domain-manager.js +37 -6
  9. package/src/cli/managers/nginx-manager.js +14 -5
  10. package/src/cli/managers/node-manager.js +19 -13
  11. package/src/cli/managers/ssl-manager.js +89 -26
  12. package/src/cli/menu.js +8 -2
  13. package/src/cli/menus/cleanup.js +4 -2
  14. package/src/cli/menus/dashboard.js +22 -15
  15. package/src/cli/menus/hub.js +381 -0
  16. package/src/cli/menus/runtime.js +12 -0
  17. package/src/cli/menus/service.js +28 -10
  18. package/src/cli/menus/settings.js +46 -12
  19. package/src/cli/menus/uninstall.js +13 -5
  20. package/src/cli/menus/update.js +24 -14
  21. package/src/cli/ui/page.js +123 -0
  22. package/src/core/cert-operations.js +34 -4
  23. package/src/core/cert-reader.js +67 -22
  24. package/src/core/cert-renewal.js +65 -9
  25. package/src/core/cert-suggest.js +120 -0
  26. package/src/core/cleanup.js +221 -1
  27. package/src/core/cloudflare-ips.js +161 -0
  28. package/src/core/daemon/ipc.js +1 -1
  29. package/src/core/daemon/lock.js +296 -9
  30. package/src/core/dashboardProcess.js +134 -6
  31. package/src/core/deploy/apps.js +36 -62
  32. package/src/core/deploy/deployKey.js +331 -0
  33. package/src/core/deploy/domainLink.js +280 -23
  34. package/src/core/deploy/engine.js +382 -63
  35. package/src/core/deploy/ezfile.js +496 -29
  36. package/src/core/deploy/githubApi.js +100 -13
  37. package/src/core/deploy/hubCommands.js +158 -18
  38. package/src/core/deploy/status.js +28 -1
  39. package/src/core/domains-db.js +1 -0
  40. package/src/core/hub/agent.js +238 -32
  41. package/src/core/hub/deployProgress.js +411 -0
  42. package/src/core/hubConnect.js +205 -0
  43. package/src/core/hubPermissions.js +48 -10
  44. package/src/core/jobs/bus.js +1 -1
  45. package/src/core/jobs/owner.js +268 -6
  46. package/src/core/nginx-conf-generator.js +124 -19
  47. package/src/core/notifications/claim.js +26 -3
  48. package/src/core/permissions.js +277 -59
  49. package/src/core/platform.js +48 -2
  50. package/src/core/runner.js +96 -40
  51. package/src/core/ssl/preflight.js +548 -0
  52. package/src/core/ssl/progress.js +196 -0
  53. package/src/core/ssl-issuer.js +502 -148
  54. package/src/core/validators.js +24 -0
  55. package/src/dashboard/controllers/authController.js +12 -5
  56. package/src/dashboard/controllers/deploymentsController.js +76 -11
  57. package/src/dashboard/controllers/domainsController.js +35 -1
  58. package/src/dashboard/controllers/hubController.js +4 -3
  59. package/src/dashboard/controllers/settingsController.js +73 -68
  60. package/src/dashboard/controllers/sslController.js +135 -15
  61. package/src/dashboard/public/js/app.js +42 -7
  62. package/src/dashboard/routes/deployments.js +2 -0
  63. package/src/dashboard/routes/domains.js +1 -0
  64. package/src/dashboard/server.js +42 -7
  65. package/src/dashboard/socketManager.js +19 -25
  66. package/src/dashboard/views/partials/settings-panel.ejs +29 -10
  67. package/dist/ui/assets/index-BUpPxWmp.css +0 -1
  68. package/dist/ui/assets/index-DD0JjK0Q.js +0 -475
  69. package/dist/ui/assets/socket-4tfdap-e.js +0 -65
@@ -1,7 +1,7 @@
1
1
  /**
2
2
  * core/deploy/ezfile.js
3
3
  *
4
- * Works out HOW a project is installed, built and started.
4
+ * Works out HOW a project is installed, built, migrated and started.
5
5
  *
6
6
  * Three sources, in order of precedence:
7
7
  *
@@ -10,10 +10,10 @@
10
10
  * 3. defaults — read from package.json, so a plain Node project deploys
11
11
  * with no configuration at all
12
12
  *
13
- * ez.json is optional. When it gives `install`, `build` and `start`, those
14
- * commands are run exactly as written, whatever the language — which is what
15
- * lets a Python or Go project deploy before anyone has written auto-detection
16
- * for it. Detection only ever saves writing the file.
13
+ * ez.json is optional. When it gives `steps`, or the older `install`, `build`,
14
+ * `migrate` and `start`, those commands are run exactly as written, whatever the
15
+ * language — which is what lets a Python or Go project deploy before anyone has
16
+ * written auto-detection for it. Detection only ever saves writing the file.
17
17
  *
18
18
  * Pure: no filesystem, no shell, no config. The engine reads the files and
19
19
  * hands their contents in, so every rule here can be tested directly.
@@ -21,21 +21,45 @@
21
21
  * ── ez.json ──────────────────────────────────────────────────────────────────
22
22
  *
23
23
  * {
24
- * "install": "npm ci", string | string[] | false
24
+ * "steps": [ at most 5, run in list order
25
+ * { "run": "npm ci", "kind": "install", "enabled": true },
26
+ * { "run": "node scripts/build.js", "kind": "build" },
27
+ * { "run": "npx prisma migrate deploy", "kind": "migrate" },
28
+ * { "run": "node scripts/seed.js", "kind": "custom" }
29
+ * ],
30
+ * "install": "npm ci", the old three fields still work
25
31
  * "build": "npm run build", string | string[] | false
26
- * "start": "node server.js", string
27
- * "port": 3000, the port the app listens on
28
- * "health": "/healthz", string, or { "path": "/healthz", "timeout": 60 }
29
- * "hooks": { "pre": "...", "post": "..." } string | string[]
30
- * "persist": ["data", "upload"], paths that survive deployments
32
+ * "migrate": "npx prisma migrate deploy" string | string[] | false
33
+ * "start": "node server.js", string
34
+ * "runtime": "node", the runtime; only "node" today
35
+ * "port": 3000, the port the app listens on
36
+ * "health": "/healthz", string, or { "path": "/healthz", "timeout": 60 }
37
+ * "hooks": { "pre": "...", "post": "..." } string | string[]
38
+ * "persist": ["data", "upload"], paths that survive deployments
39
+ * "instances": 2, 1..CPU count, or "max"
40
+ * "execMode": "cluster" "fork" (default) | "cluster"
31
41
  * }
32
42
  *
33
43
  * A persistent path is a folder or a single file.
34
44
  *
35
- * `false` (or an empty string) switches a step off — "this project has no
36
- * build" is a real answer, and different from "work it out for me".
45
+ * `false` (or an empty string) switches an old command off — "this project has
46
+ * no build" is a real answer, and different from "work it out for me". A
47
+ * skipped old field contributes no step. When `steps` and the old fields are
48
+ * both present, `steps` wins and the old fields are ignored with a warning.
49
+ *
50
+ * ── The order the engine runs them in ────────────────────────────────────────
51
+ *
52
+ * hooks.pre → steps (in list order) → start → health → hooks.post
53
+ *
54
+ * Every step runs in the NEW release directory, with the app's deploy
55
+ * environment. `migrate` keeps its forward-only hint. A non-zero exit aborts the
56
+ * deployment at that step; the previous release keeps running untouched.
57
+ * Migrations are forward-only: a code rollback cannot undo one that already ran,
58
+ * so keep each migration backward-compatible for one release.
37
59
  */
38
60
 
61
+ import os from 'os';
62
+
39
63
  /** Where ez.json may live, relative to the repository root, first match wins. */
40
64
  export const EZ_FILE_LOCATIONS = Object.freeze(['ez.json', 'deploy/ez.json', '.deploy/ez.json']);
41
65
 
@@ -43,8 +67,54 @@ export const DEFAULT_HEALTH_PATH = '/';
43
67
  export const DEFAULT_HEALTH_TIMEOUT_S = 60;
44
68
  export const MAX_HEALTH_TIMEOUT_S = 600;
45
69
 
46
- const COMMAND_FIELDS = Object.freeze(['install', 'build']);
47
- const KNOWN_KEYS = Object.freeze(['$schema', 'name', 'install', 'build', 'start', 'port', 'health', 'hooks', 'persist']);
70
+ export const EXEC_MODES = Object.freeze(['fork', 'cluster']);
71
+
72
+ export const CLUSTER_STATELESS_WARNING =
73
+ 'Cluster mode runs several copies of the app; it must be stateless ' +
74
+ '(no in-memory sessions, sockets, caches or schedulers that assume one process).';
75
+
76
+ function clusterStartError(start) {
77
+ return `execMode "cluster" needs a Node app started directly, such as "node dist/index.js" or ` +
78
+ `"node server.mjs". "${start}" cannot run in cluster mode — change the start command to "node <file>".`;
79
+ }
80
+
81
+ function forkInstancesError(instances) {
82
+ return `instances is ${instances} but execMode is "fork". Fork mode runs one process, and several ` +
83
+ 'copies would all try to bind the same port. Set execMode to "cluster" to run more than one instance.';
84
+ }
85
+
86
+ /**
87
+ * The CPUs this machine offers PM2's cluster mode.
88
+ * os.availableParallelism() respects cgroup/affinity limits where it exists;
89
+ * os.cpus() is the fallback on older Node versions.
90
+ *
91
+ * @returns {number}
92
+ */
93
+ export function availableCpuCount() {
94
+ try {
95
+ if (typeof os.availableParallelism === 'function') return Math.max(1, os.availableParallelism());
96
+ } catch { /* fall through */ }
97
+ try {
98
+ return Math.max(1, os.cpus()?.length ?? 1);
99
+ } catch {
100
+ return 1;
101
+ }
102
+ }
103
+
104
+ const COMMAND_FIELDS = Object.freeze(['install', 'build', 'migrate']);
105
+
106
+ /** Runtimes an app may run on. Only Node today; the list is the extension point. */
107
+ export const RUNTIMES = Object.freeze(['node']);
108
+
109
+ /** What a step does. `custom` has no special handling. */
110
+ export const STEP_KINDS = Object.freeze(['install', 'build', 'migrate', 'custom']);
111
+
112
+ export const MAX_STEPS = 5;
113
+
114
+ const KNOWN_KEYS = Object.freeze([
115
+ '$schema', 'name', 'install', 'build', 'migrate', 'steps', 'start', 'runtime', 'port', 'health', 'hooks', 'persist',
116
+ 'instances', 'execMode',
117
+ ]);
48
118
  const MAX_COMMAND_LENGTH = 2000;
49
119
 
50
120
  export const MAX_PERSIST_PATHS = 20;
@@ -82,6 +152,127 @@ export function normalizeCommands(value) {
82
152
  return { commands: out, disabled: false, error: null };
83
153
  }
84
154
 
155
+ /**
156
+ * Normalises a `steps` field to the ordered list a deployment runs.
157
+ *
158
+ * A step is `{ run, kind, enabled }`, where `run` is one command line (the
159
+ * same validation as the old install/build/migrate fields), `kind` is one of
160
+ * STEP_KINDS, and `enabled` defaults to true. `false` or `[]` is the explicit
161
+ * "no steps" answer that clears a list from a lower-precedence source;
162
+ * `null`/`undefined` means "not specified here".
163
+ *
164
+ * @param {*} value
165
+ * @returns {{ steps: Array<{run:string,kind:string,enabled:boolean}>|null, error: string|null }}
166
+ */
167
+ export function normalizeSteps(value) {
168
+ if (value === undefined || value === null) return { steps: null, error: null };
169
+ if (value === false) return { steps: [], error: null };
170
+ if (!Array.isArray(value)) return { steps: null, error: `must be a list of steps (at most ${MAX_STEPS})` };
171
+ if (value.length > MAX_STEPS) return { steps: null, error: `has more than ${MAX_STEPS} steps` };
172
+
173
+ const steps = [];
174
+ for (let i = 0; i < value.length; i++) {
175
+ const raw = value[i];
176
+ const at = `step ${i + 1}`;
177
+ if (!isPlainObject(raw)) {
178
+ return { steps: null, error: `${at} must be an object with "run", "kind" and optionally "enabled"` };
179
+ }
180
+
181
+ const command = normalizeCommands(raw.run);
182
+ if (command.error) return { steps: null, error: `${at} "run" ${command.error}` };
183
+ if (command.disabled || command.commands.length !== 1) {
184
+ return { steps: null, error: `${at} "run" must be a single non-empty command` };
185
+ }
186
+
187
+ const kind = typeof raw.kind === 'string' ? raw.kind.trim().toLowerCase() : '';
188
+ if (!STEP_KINDS.includes(kind)) {
189
+ return { steps: null, error: `${at} "kind" must be one of: ${STEP_KINDS.join(', ')}` };
190
+ }
191
+
192
+ if (raw.enabled !== undefined && typeof raw.enabled !== 'boolean') {
193
+ return { steps: null, error: `${at} "enabled" must be true or false` };
194
+ }
195
+
196
+ steps.push({ run: command.commands[0], kind, enabled: raw.enabled !== false });
197
+ }
198
+
199
+ return { steps, error: null };
200
+ }
201
+
202
+ /**
203
+ * The steps an older app or ez.json describes with install/build/migrate.
204
+ * A skipped field (false or an empty list) contributes no step: the two
205
+ * representations have the same effect, and an omitted step cannot be
206
+ * confused with a disabled one.
207
+ *
208
+ * @param {{install?:string[],build?:string[],migrate?:string[]}} commands
209
+ * @returns {Array<{run:string,kind:string,enabled:boolean}>}
210
+ */
211
+ export function stepsFromCommands(commands = {}) {
212
+ const steps = [];
213
+ for (const kind of ['install', 'build', 'migrate']) {
214
+ const commandsForKind = commands[kind];
215
+ if (typeof commandsForKind === 'string' && commandsForKind.trim()) {
216
+ steps.push({ run: commandsForKind.trim(), kind, enabled: true });
217
+ continue;
218
+ }
219
+ for (const run of Array.isArray(commandsForKind) ? commandsForKind : []) {
220
+ steps.push({ run, kind, enabled: true });
221
+ }
222
+ }
223
+ return steps;
224
+ }
225
+
226
+ /**
227
+ * Advisory notes for a list whose order would probably fail. Only enabled
228
+ * steps are considered, and nothing here is an error: a custom step may
229
+ * legitimately put a command between them.
230
+ *
231
+ * @param {Array<{kind:string,enabled?:boolean}>} steps
232
+ * @returns {string[]}
233
+ */
234
+ export function stepOrderWarnings(steps = []) {
235
+ const first = {};
236
+ steps.forEach((step, index) => {
237
+ if (step?.enabled === false) return;
238
+ if (!(step?.kind in first)) first[step.kind] = index;
239
+ });
240
+
241
+ const warnings = [];
242
+ const before = (a, b, advice) => {
243
+ if (first[a] !== undefined && first[b] !== undefined && first[a] < first[b]) warnings.push(advice);
244
+ };
245
+
246
+ before(
247
+ 'migrate', 'install',
248
+ `The "migrate" step is listed before "install", but dependencies are not installed yet. Put "install" before "migrate".`,
249
+ );
250
+ before(
251
+ 'build', 'install',
252
+ `The "build" step is listed before "install", but dependencies are not installed yet. Put "install" before "build".`,
253
+ );
254
+ before(
255
+ 'migrate', 'build',
256
+ `The "migrate" step is listed before "build". Build first, then migrate, so the migration runs against the release that is about to start.`,
257
+ );
258
+ return warnings;
259
+ }
260
+
261
+ /**
262
+ * Validates a `runtime` value.
263
+ * @param {*} value
264
+ * @returns {{ value: string|null, error: string|null }}
265
+ */
266
+ export function normalizeRuntime(value) {
267
+ if (value === undefined || value === null || value === '') return { value: null, error: null };
268
+ const runtime = String(value).trim().toLowerCase();
269
+ if (RUNTIMES.includes(runtime)) return { value: runtime, error: null };
270
+ return {
271
+ value: null,
272
+ error: `must be one of: ${RUNTIMES.join(', ')}. Leave it out to use "node".`,
273
+ };
274
+ }
275
+
85
276
  /**
86
277
  * Validates a port value.
87
278
  * @returns {number|null} The port, or null when it is not usable
@@ -100,6 +291,114 @@ export function normalizeHealthPath(value) {
100
291
  return p;
101
292
  }
102
293
 
294
+ /**
295
+ * Validates an `instances` value: a whole number from 1 to the CPU count, or
296
+ * the string "max". A number above the CPU count is refused rather than
297
+ * clamped: the operator asked for something the machine cannot do, and PM2
298
+ * would otherwise silently start fewer workers than the file says.
299
+ *
300
+ * @param {*} value
301
+ * @param {number} [cpu]
302
+ * @returns {{ value: number|'max'|null, error: string|null }}
303
+ */
304
+ export function normalizeInstances(value, cpu = availableCpuCount()) {
305
+ if (value === undefined || value === null || value === '') return { value: null, error: null };
306
+
307
+ if (typeof value === 'string') {
308
+ const text = value.trim();
309
+ if (text === '') return { value: null, error: null };
310
+ if (text.toLowerCase() === 'max') return { value: 'max', error: null };
311
+ const asNumber = Number(text);
312
+ if (!Number.isFinite(asNumber) || !Number.isInteger(asNumber)) {
313
+ return {
314
+ value: null,
315
+ error: `must be a whole number from 1 to ${cpu} (this server has ${cpu} CPU${cpu === 1 ? '' : 's'}), or "max"`,
316
+ };
317
+ }
318
+ return normalizeInstances(asNumber, cpu);
319
+ }
320
+
321
+ if (typeof value !== 'number' || !Number.isFinite(value) || !Number.isInteger(value)) {
322
+ return {
323
+ value: null,
324
+ error: `must be a whole number from 1 to ${cpu} (this server has ${cpu} CPU${cpu === 1 ? '' : 's'}), or "max"`,
325
+ };
326
+ }
327
+ if (value < 1 || value > cpu) {
328
+ return {
329
+ value: null,
330
+ error: `must be from 1 to ${cpu} — this server has ${cpu} CPU${cpu === 1 ? '' : 's'}. Use "max" for one per CPU`,
331
+ };
332
+ }
333
+ return { value, error: null };
334
+ }
335
+
336
+ /**
337
+ * Validates an `execMode` value.
338
+ * @param {*} value
339
+ * @returns {{ value: 'fork'|'cluster'|null, error: string|null }}
340
+ */
341
+ export function normalizeExecMode(value) {
342
+ if (value === undefined || value === null || value === '') return { value: null, error: null };
343
+ const mode = String(value).trim().toLowerCase();
344
+ if (mode === 'fork' || mode === 'cluster') return { value: mode, error: null };
345
+ return {
346
+ value: null,
347
+ error: 'must be "fork" (one process, the default) or "cluster" (one process per instance)',
348
+ };
349
+ }
350
+
351
+ /**
352
+ * The checks that need the resolved start command and both runtime fields.
353
+ *
354
+ * `assumeFork` marks a layer whose omitted execMode really means fork: the
355
+ * app's own settings form. In an ez.json layer an omitted value may still be
356
+ * supplied by an app override, so only an explicit "fork" is judged there.
357
+ *
358
+ * @param {{ start?: string|null, instances?: number|'max'|null, execMode?: string|null, runtime?: string|null }} settings
359
+ * @param {{ assumeFork?: boolean }} [opts]
360
+ * @returns {{ errors: string[], warnings: string[] }}
361
+ */
362
+ function runtimeValidation(settings, { assumeFork = false } = {}) {
363
+ const errors = [];
364
+ const warnings = [];
365
+
366
+ const mode = settings.execMode ?? (assumeFork ? 'fork' : null);
367
+ const runtime = settings.runtime ?? 'node';
368
+ const instances = settings.instances === 'max'
369
+ ? availableCpuCount()
370
+ : (settings.instances ?? (assumeFork ? 1 : null));
371
+
372
+ if (mode === 'cluster') {
373
+ warnings.push(CLUSTER_STATELESS_WARNING);
374
+ if (runtime !== 'node') {
375
+ errors.push(
376
+ `execMode "cluster" is only available for runtime "node". Set runtime to "node", ` +
377
+ `or set execMode to "fork" for runtime "${runtime}".`,
378
+ );
379
+ }
380
+ if (settings.start && parseStartCommand(settings.start).kind !== 'node') {
381
+ errors.push(clusterStartError(settings.start));
382
+ }
383
+ }
384
+
385
+ if (instances !== null && instances > 1 && mode === 'fork') {
386
+ errors.push(forkInstancesError(instances));
387
+ }
388
+
389
+ return { errors, warnings };
390
+ }
391
+
392
+ /** The advisory strings that belong with a set of (already normalized) settings. */
393
+ export function settingsWarnings(settings = {}) {
394
+ const warnings = String(settings?.execMode ?? '').toLowerCase() === 'cluster' ? [CLUSTER_STATELESS_WARNING] : [];
395
+ const steps = Array.isArray(settings?.steps) ? settings.steps : stepsFromCommands(settings);
396
+ for (const warning of stepOrderWarnings(steps)) {
397
+ if (!warnings.includes(warning)) warnings.push(warning);
398
+ }
399
+ return warnings;
400
+ }
401
+
103
402
  /**
104
403
  * A `persist` path must stay inside the project and name a folder or a file.
105
404
  *
@@ -201,6 +500,18 @@ export function parseEzFile(text) {
201
500
  else if (n.commands !== null) value[field] = n.commands;
202
501
  }
203
502
 
503
+ if (raw.steps !== undefined && raw.steps !== null) {
504
+ const n = normalizeSteps(raw.steps);
505
+ if (n.error) errors.push(`ez.json: "steps" ${n.error}`);
506
+ else {
507
+ value.steps = n.steps;
508
+ if (COMMAND_FIELDS.some((field) => raw[field] !== undefined && raw[field] !== null)) {
509
+ warnings.push('ez.json: "steps" is set, so "install", "build" and "migrate" were ignored.');
510
+ for (const field of COMMAND_FIELDS) delete value[field];
511
+ }
512
+ }
513
+ }
514
+
204
515
  if (raw.start !== undefined && raw.start !== null) {
205
516
  const n = normalizeCommands(raw.start);
206
517
  if (n.error) errors.push(`ez.json: "start" ${n.error}`);
@@ -257,6 +568,36 @@ export function parseEzFile(text) {
257
568
  else if (n.paths !== null) value.persist = n.paths;
258
569
  }
259
570
 
571
+ if (raw.instances !== undefined && raw.instances !== null) {
572
+ const n = normalizeInstances(raw.instances);
573
+ if (n.error) errors.push(`ez.json: "instances" ${n.error}`);
574
+ else if (n.value !== null) value.instances = n.value;
575
+ }
576
+
577
+ if (raw.execMode !== undefined && raw.execMode !== null) {
578
+ const n = normalizeExecMode(raw.execMode);
579
+ if (n.error) errors.push(`ez.json: "execMode" ${n.error}`);
580
+ else if (n.value !== null) value.execMode = n.value;
581
+ }
582
+
583
+ if (raw.runtime !== undefined && raw.runtime !== null) {
584
+ const n = normalizeRuntime(raw.runtime);
585
+ if (n.error) errors.push(`ez.json: "runtime" ${n.error}`);
586
+ else if (n.value !== null) value.runtime = n.value;
587
+ }
588
+
589
+ const runtime = runtimeValidation({
590
+ start: value.start ?? null,
591
+ instances: value.instances ?? null,
592
+ execMode: value.execMode ?? null,
593
+ runtime: value.runtime ?? (raw.runtime ? String(raw.runtime) : null),
594
+ });
595
+ errors.push(...runtime.errors);
596
+ warnings.push(...runtime.warnings);
597
+ for (const warning of stepOrderWarnings(value.steps ?? stepsFromCommands(value))) {
598
+ if (!warnings.includes(warning)) warnings.push(warning);
599
+ }
600
+
260
601
  return { ok: errors.length === 0, value: errors.length === 0 ? value : null, errors, warnings };
261
602
  }
262
603
 
@@ -296,22 +637,44 @@ export function defaultsFromPackageJson(pkg, files = {}) {
296
637
  /**
297
638
  * Validates the per-app overrides set in the dashboard or the Hub.
298
639
  *
299
- * Same shape as a parsed ez.json (`install`, `build`, `start`, `port`,
300
- * `healthPath`, `healthTimeout`, `pre`, `post`, `persist`). An absent, null or
301
- * empty field means "do not override", so a form with untouched inputs
302
- * overrides nothing. `false` for install/build/pre/post switches that step off;
303
- * `[]` or `false` for persist means "nothing persistent", overriding ez.json.
640
+ * Same shape as a parsed ez.json (`install`, `build`, `migrate`, `start`,
641
+ * `port`, `healthPath`, `healthTimeout`, `pre`, `post`, `persist`). An absent,
642
+ * null or empty field means "do not override", so a form with untouched inputs
643
+ * overrides nothing. `false` for install/build/migrate/pre/post switches that
644
+ * step off; `[]` or `false` for persist means "nothing persistent", overriding
645
+ * ez.json.
304
646
  *
305
647
  * @param {*} input
306
- * @returns {{ ok: boolean, value: Object, errors: string[] }}
648
+ * @returns {{ ok: boolean, value: Object, errors: string[], warnings: string[] }}
307
649
  */
308
650
  export function normalizeOverrides(input) {
309
651
  const errors = [];
652
+ const warnings = [];
310
653
  const value = {};
311
- if (input === undefined || input === null) return { ok: true, value, errors };
312
- if (!isPlainObject(input)) return { ok: false, value, errors: ['settings must be an object'] };
654
+ if (input === undefined || input === null) return { ok: true, value, errors, warnings };
655
+ if (!isPlainObject(input)) return { ok: false, value, errors: ['settings must be an object'], warnings };
656
+
657
+ const stepsPresent = input.steps !== undefined && input.steps !== null && input.steps !== '';
658
+ const legacyPresent = COMMAND_FIELDS.some((field) => input[field] !== undefined && input[field] !== null);
659
+
660
+ if (stepsPresent) {
661
+ const n = normalizeSteps(input.steps);
662
+ if (n.error) errors.push(`steps ${n.error}`);
663
+ else {
664
+ value.steps = n.steps;
665
+ if (legacyPresent) warnings.push('"steps" is set, so "install", "build" and "migrate" were ignored.');
666
+ }
667
+ } else {
668
+ for (const field of COMMAND_FIELDS) {
669
+ const raw = input[field];
670
+ if (raw === undefined || raw === null || raw === '') continue;
671
+ const n = normalizeCommands(raw);
672
+ if (n.error) errors.push(`${field} ${n.error}`);
673
+ else if (n.commands !== null) value[field] = n.commands;
674
+ }
675
+ }
313
676
 
314
- for (const field of ['install', 'build', 'pre', 'post']) {
677
+ for (const field of ['pre', 'post']) {
315
678
  const raw = input[field];
316
679
  if (raw === undefined || raw === null || raw === '') continue;
317
680
  const n = normalizeCommands(raw);
@@ -353,7 +716,39 @@ export function normalizeOverrides(input) {
353
716
  else if (n.paths !== null) value.persist = n.paths;
354
717
  }
355
718
 
356
- return { ok: errors.length === 0, value, errors };
719
+ if (input.instances !== undefined && input.instances !== null && input.instances !== '') {
720
+ const n = normalizeInstances(input.instances);
721
+ if (n.error) errors.push(`instances ${n.error}`);
722
+ else if (n.value !== null) value.instances = n.value;
723
+ }
724
+
725
+ if (input.execMode !== undefined && input.execMode !== null && input.execMode !== '') {
726
+ const n = normalizeExecMode(input.execMode);
727
+ if (n.error) errors.push(`execMode ${n.error}`);
728
+ else if (n.value !== null) value.execMode = n.value;
729
+ }
730
+
731
+ if (input.runtime !== undefined && input.runtime !== null && input.runtime !== '') {
732
+ const n = normalizeRuntime(input.runtime);
733
+ if (n.error) errors.push(`runtime ${n.error}`);
734
+ else if (n.value !== null) value.runtime = n.value;
735
+ }
736
+
737
+ const runtime = runtimeValidation({
738
+ start: value.start ?? null,
739
+ instances: value.instances ?? null,
740
+ execMode: value.execMode ?? null,
741
+ runtime: value.runtime ?? (input.runtime !== undefined && input.runtime !== null && input.runtime !== ''
742
+ ? String(input.runtime)
743
+ : null),
744
+ }, { assumeFork: true });
745
+ errors.push(...runtime.errors);
746
+ warnings.push(...runtime.warnings);
747
+ for (const warning of stepOrderWarnings(value.steps ?? stepsFromCommands(value))) {
748
+ if (!warnings.includes(warning)) warnings.push(warning);
749
+ }
750
+
751
+ return { ok: errors.length === 0, value, errors, warnings };
357
752
  }
358
753
 
359
754
  /**
@@ -370,10 +765,12 @@ export function normalizeOverrides(input) {
370
765
  * @param {Object} [input.overrides] Value from normalizeOverrides()
371
766
  * @returns {{
372
767
  * ok: boolean, error: string|null,
373
- * settings: { install: string[], build: string[], start: string|null, port: number|null,
768
+ * settings: { install: string[], build: string[], migrate: string[], steps: Array<Object>, start: string|null,
769
+ * runtime: string, port: number|null,
374
770
  * healthPath: string, healthTimeout: number, pre: string[], post: string[],
375
- * persist: string[] },
376
- * sources: Object<string, 'override'|'ez.json'|'package.json'|'default'>
771
+ * persist: string[], instances: number|'max', execMode: 'fork'|'cluster' },
772
+ * sources: Object<string, 'override'|'ez.json'|'package.json'|'default'>,
773
+ * warnings: string[]
377
774
  * }}
378
775
  */
379
776
  export function resolveSettings({ ez = null, pkg = null, files = {}, overrides = {} } = {}) {
@@ -399,15 +796,75 @@ export function resolveSettings({ ez = null, pkg = null, files = {}, overrides =
399
796
  const settings = {
400
797
  install: pick('install', []),
401
798
  build: pick('build', []),
799
+ migrate: pick('migrate', []),
402
800
  start: pick('start', null),
801
+ runtime: pick('runtime', 'node'),
403
802
  port: pick('port', null),
404
803
  healthPath: pick('healthPath', DEFAULT_HEALTH_PATH),
405
804
  healthTimeout: pick('healthTimeout', DEFAULT_HEALTH_TIMEOUT_S),
406
805
  pre: pick('pre', []),
407
806
  post: pick('post', []),
408
807
  persist: pick('persist', []),
808
+ instances: pick('instances', 1),
809
+ execMode: pick('execMode', 'fork'),
409
810
  };
410
811
 
812
+ // `steps` is one field: the first layer that states it wins whole. When no
813
+ // layer does, the old install/build/migrate fields are read as the same
814
+ // list, so an existing app or ez.json deploys exactly as before.
815
+ //
816
+ // A higher layer can still be an older app whose stored settings use the old
817
+ // fields. App settings must keep winning: when a layer above the one that
818
+ // states `steps` has any old command fields, those become the list and the
819
+ // lower `steps` are not used.
820
+ const precedenceWarnings = [];
821
+ const explicitIndex = layers.findIndex(([, layer]) => layer.steps !== undefined && layer.steps !== null);
822
+ const higherWithLegacy = explicitIndex > 0
823
+ ? layers.slice(0, explicitIndex).find(([, layer]) => COMMAND_FIELDS.some(
824
+ (field) => layer[field] !== undefined && layer[field] !== null,
825
+ ))
826
+ : null;
827
+
828
+ if (explicitIndex !== -1 && higherWithLegacy) {
829
+ const higherLayers = layers.slice(0, explicitIndex);
830
+ const higherCommands = {};
831
+ const higherSources = {};
832
+ for (const field of COMMAND_FIELDS) {
833
+ const found = higherLayers.find(([, layer]) => layer[field] !== undefined && layer[field] !== null);
834
+ higherCommands[field] = found ? found[1][field] : [];
835
+ higherSources[field] = found ? found[0] : 'default';
836
+ }
837
+
838
+ settings.steps = stepsFromCommands(higherCommands);
839
+ sources.steps = higherWithLegacy[0];
840
+ for (const field of COMMAND_FIELDS) {
841
+ settings[field] = settings.steps.filter((s) => s.enabled !== false && s.kind === field).map((s) => s.run);
842
+ sources[field] = higherSources[field];
843
+ }
844
+
845
+ const stepsLayer = layers[explicitIndex][0];
846
+ const higherName = higherWithLegacy[0] === 'override' ? "The app's" : `The "${higherWithLegacy[0]}"`;
847
+ precedenceWarnings.push(
848
+ `${higherName} install/build/migrate settings override the "steps" in ${stepsLayer}. ` +
849
+ `Save the app's commands as steps to make this explicit.`,
850
+ );
851
+ } else if (explicitIndex !== -1) {
852
+ settings.steps = layers[explicitIndex][1].steps;
853
+ sources.steps = layers[explicitIndex][0];
854
+ // Keep the legacy fields meaningful for older readers and the run log.
855
+ // They are informational only: the engine runs settings.steps.
856
+ for (const field of COMMAND_FIELDS) {
857
+ settings[field] = settings.steps.filter((s) => s.enabled !== false && s.kind === field).map((s) => s.run);
858
+ sources[field] = sources.steps;
859
+ }
860
+ } else {
861
+ settings.steps = stepsFromCommands(settings);
862
+ const legacyLayer = layers.find(([, layer]) => COMMAND_FIELDS.some(
863
+ (field) => layer[field] !== undefined && layer[field] !== null,
864
+ ));
865
+ sources.steps = legacyLayer ? legacyLayer[0] : 'default';
866
+ }
867
+
411
868
  if (!settings.start) {
412
869
  return {
413
870
  ok: false,
@@ -416,10 +873,20 @@ export function resolveSettings({ ez = null, pkg = null, files = {}, overrides =
416
873
  'or give package.json a "start" script or a "main" file.',
417
874
  settings,
418
875
  sources,
876
+ warnings: [...new Set([...settingsWarnings(settings), ...precedenceWarnings])],
419
877
  };
420
878
  }
421
879
 
422
- return { ok: true, error: null, settings, sources };
880
+ const runtime = runtimeValidation(settings, { assumeFork: true });
881
+ const warnings = [...runtime.warnings];
882
+ for (const warning of [...stepOrderWarnings(settings.steps), ...precedenceWarnings]) {
883
+ if (!warnings.includes(warning)) warnings.push(warning);
884
+ }
885
+ if (runtime.errors.length > 0) {
886
+ return { ok: false, error: runtime.errors.join(' '), settings, sources, warnings };
887
+ }
888
+
889
+ return { ok: true, error: null, settings, sources, warnings };
423
890
  }
424
891
 
425
892
  /**