hermes-agent 0.22.2 → 0.22.4
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.
- package/README.md +211 -33
- package/SECURITY.md +84 -19
- package/lib/npm-channel.js +211 -49
- package/lib/provision.js +177 -0
- package/lib/python-launcher.js +67 -9
- package/lib/upstream-migration.js +2 -1
- package/lib/upstream-ownership.js +281 -0
- package/package.json +5 -5
- package/scripts/postinstall.js +49 -3
package/lib/npm-channel.js
CHANGED
|
@@ -1,21 +1,33 @@
|
|
|
1
|
-
const {
|
|
1
|
+
const { spawnSync } = require("node:child_process");
|
|
2
2
|
const fs = require("node:fs");
|
|
3
3
|
const path = require("node:path");
|
|
4
4
|
|
|
5
5
|
const packageJson = require("../package.json");
|
|
6
|
-
const {
|
|
6
|
+
const { provisionRuntime } = require("./provision");
|
|
7
|
+
const {
|
|
8
|
+
getRuntimeSourceDirectory,
|
|
9
|
+
resolveRuntimeSourceDirectory,
|
|
10
|
+
venvConsoleExecutable
|
|
11
|
+
} = require("./python-launcher");
|
|
7
12
|
const {
|
|
8
13
|
createUpstreamMigrationPlan,
|
|
9
14
|
executeUpstreamMigration,
|
|
10
15
|
getDefaultHermesHome
|
|
11
16
|
} = require("./upstream-migration");
|
|
17
|
+
const { readUpstreamOwnership } = require("./upstream-ownership");
|
|
12
18
|
|
|
13
19
|
const packageRoot = path.resolve(__dirname, "..");
|
|
14
20
|
const npmRegistry = "https://registry.npmjs.org";
|
|
15
21
|
const canonicalPackageName = packageJson.hermesAgent?.canonicalNpmPackage || packageJson.name;
|
|
16
22
|
|
|
17
|
-
|
|
18
|
-
|
|
23
|
+
// Node refuses to spawn .cmd files without a shell (CVE-2024-27980), so on
|
|
24
|
+
// Windows npm is started through cmd.exe. Every argument passed here is a
|
|
25
|
+
// fixed token or a validated semver/package name.
|
|
26
|
+
function getNpmSpawnSpec(args, platform = process.platform, env = process.env) {
|
|
27
|
+
if (platform === "win32") {
|
|
28
|
+
return { command: env.ComSpec || "cmd.exe", args: ["/d", "/s", "/c", "npm", ...args] };
|
|
29
|
+
}
|
|
30
|
+
return { command: "npm", args: [...args] };
|
|
19
31
|
}
|
|
20
32
|
|
|
21
33
|
function runGit(args, options = {}) {
|
|
@@ -50,6 +62,15 @@ function isReleasePinned(runtimeReady, runtimeCommit, packagedCommit, runtimeDir
|
|
|
50
62
|
);
|
|
51
63
|
}
|
|
52
64
|
|
|
65
|
+
// The release channel needs both the pinned source and npm's own dependency
|
|
66
|
+
// environment. Once upstream's package manager has recorded an environment
|
|
67
|
+
// for the checkout, or stamped it as self-managed, upstream decides what runs
|
|
68
|
+
// even when the commit still matches the npm Release.
|
|
69
|
+
function getRuntimeChannel(runtimeReady, releasePinned, upstreamManaged) {
|
|
70
|
+
if (!runtimeReady) return "missing";
|
|
71
|
+
return releasePinned && !upstreamManaged ? "npm-release" : "upstream-native";
|
|
72
|
+
}
|
|
73
|
+
|
|
53
74
|
function findNodeModulesOwner(startPath) {
|
|
54
75
|
let current = path.resolve(startPath);
|
|
55
76
|
while (true) {
|
|
@@ -69,13 +90,25 @@ function pathsReferToSameInstallLocation(left, right, platform = process.platfor
|
|
|
69
90
|
: left === right;
|
|
70
91
|
}
|
|
71
92
|
|
|
93
|
+
// Node.js loads modules from their real path, while 'npm root --global' can
|
|
94
|
+
// report a path through a symlink (macOS /var -> /private/var, symlinked
|
|
95
|
+
// prefixes), so compare real paths.
|
|
96
|
+
function realPathOrSelf(target) {
|
|
97
|
+
try {
|
|
98
|
+
return fs.realpathSync.native(target);
|
|
99
|
+
} catch {
|
|
100
|
+
return target;
|
|
101
|
+
}
|
|
102
|
+
}
|
|
103
|
+
|
|
72
104
|
function detectInstallContext() {
|
|
73
|
-
const
|
|
105
|
+
const npm = getNpmSpawnSpec(["root", "--global"]);
|
|
106
|
+
const result = spawnSync(npm.command, npm.args, {
|
|
74
107
|
encoding: "utf8",
|
|
75
108
|
windowsHide: true
|
|
76
109
|
});
|
|
77
|
-
const globalRoot = result.status === 0 ? path.resolve(result.stdout.trim()) : null;
|
|
78
|
-
const packageParent = path.dirname(packageRoot);
|
|
110
|
+
const globalRoot = result.status === 0 ? realPathOrSelf(path.resolve(result.stdout.trim())) : null;
|
|
111
|
+
const packageParent = realPathOrSelf(path.dirname(packageRoot));
|
|
79
112
|
const isGlobal = pathsReferToSameInstallLocation(packageParent, globalRoot);
|
|
80
113
|
return {
|
|
81
114
|
isGlobal,
|
|
@@ -187,6 +220,22 @@ function readRuntimeStatus() {
|
|
|
187
220
|
runtimeDirtyPaths
|
|
188
221
|
);
|
|
189
222
|
const context = detectInstallContext();
|
|
223
|
+
const venvDirectory = path.join(sourceDirectory, "venv");
|
|
224
|
+
const ownership = readUpstreamOwnership(sourceDirectory, {
|
|
225
|
+
isTracked: (file) => {
|
|
226
|
+
const tracked = runGit(["-C", sourceDirectory, "ls-files", "--", file]);
|
|
227
|
+
return tracked === null ? null : tracked !== "";
|
|
228
|
+
}
|
|
229
|
+
});
|
|
230
|
+
const upstreamOwnsDependencies = ownership.dependenciesOwner === "upstream-pm";
|
|
231
|
+
const runtimeChannel = getRuntimeChannel(
|
|
232
|
+
runtimeReady,
|
|
233
|
+
releasePinned,
|
|
234
|
+
upstreamOwnsDependencies || ownership.selfManagedStamp
|
|
235
|
+
);
|
|
236
|
+
let dependenciesOwner = null;
|
|
237
|
+
if (upstreamOwnsDependencies) dependenciesOwner = "upstream-pm";
|
|
238
|
+
else if (runtimeReady) dependenciesOwner = "npm";
|
|
190
239
|
|
|
191
240
|
return {
|
|
192
241
|
installation: "npm",
|
|
@@ -197,19 +246,28 @@ function readRuntimeStatus() {
|
|
|
197
246
|
packagedCommit,
|
|
198
247
|
runtimeCommit,
|
|
199
248
|
runtimeSourceDirectory: sourceDirectory,
|
|
200
|
-
runtimeVenvDirectory:
|
|
249
|
+
runtimeVenvDirectory: venvDirectory,
|
|
201
250
|
runtimeBranch: branch || null,
|
|
202
251
|
runtimeDirty: runtimeDirtyPaths === null ? null : runtimeDirtyPaths.length > 0,
|
|
203
252
|
runtimeDirtyPaths,
|
|
204
253
|
runtimeReady,
|
|
205
|
-
runtimeChannel
|
|
206
|
-
runtimeModifiedByNativeUpdate: runtimeReady ?
|
|
254
|
+
runtimeChannel,
|
|
255
|
+
runtimeModifiedByNativeUpdate: runtimeReady ? runtimeChannel !== "npm-release" : null,
|
|
256
|
+
dependenciesOwner,
|
|
257
|
+
dependencyEnvironment: upstreamOwnsDependencies
|
|
258
|
+
? ownership.dependencyEnvironment
|
|
259
|
+
: dependenciesOwner === "npm" ? venvDirectory : null,
|
|
260
|
+
dependencyRecordError: ownership.factsError,
|
|
261
|
+
upstreamInstallState: ownership.installStateDirectory,
|
|
262
|
+
upstreamInstallStamp: ownership.installStamp,
|
|
263
|
+
upstreamSelfManagedStamp: ownership.selfManagedStamp,
|
|
207
264
|
nativeUpdateCommand: "hermes update",
|
|
208
265
|
nativeCheckCommand: "hermes update --check",
|
|
209
266
|
releaseUpdateCommand: getReleaseUpdateCommand(),
|
|
210
267
|
releaseCheckCommand: "hermes-npm check",
|
|
211
268
|
installMethodsCommand: "hermes-npm methods --json",
|
|
212
269
|
hermesHome,
|
|
270
|
+
hermesRoot: ownership.hermesRoot,
|
|
213
271
|
upstreamHandoffTarget: path.join(hermesHome, "hermes-agent"),
|
|
214
272
|
installScope: context.isGlobal ? "global" : "local"
|
|
215
273
|
};
|
|
@@ -242,11 +300,31 @@ function printStatus(status) {
|
|
|
242
300
|
console.log(`runtime source: ${status.runtimeSourceDirectory}`);
|
|
243
301
|
console.log(`HERMES_HOME: ${status.hermesHome}`);
|
|
244
302
|
console.log(`runtime channel: ${status.runtimeChannel}`);
|
|
303
|
+
if (status.dependenciesOwner === "upstream-pm") {
|
|
304
|
+
console.log(`dependencies: upstream package manager (${status.dependencyEnvironment || "no environment recorded"})`);
|
|
305
|
+
console.log(`upstream record: ${status.upstreamInstallState}`);
|
|
306
|
+
} else if (status.dependenciesOwner === "npm") {
|
|
307
|
+
console.log(`dependencies: npm package venv (${status.dependencyEnvironment})`);
|
|
308
|
+
}
|
|
309
|
+
if (status.upstreamSelfManagedStamp) {
|
|
310
|
+
console.log(`install stamp: ${status.upstreamInstallStamp.path} (updateMechanism: self, untracked)`);
|
|
311
|
+
}
|
|
245
312
|
console.log(`native update: ${status.nativeUpdateCommand}`);
|
|
246
313
|
console.log(`release update: ${status.releaseUpdateCommand}`);
|
|
314
|
+
if (status.dependencyRecordError) {
|
|
315
|
+
console.log(`warning: ${status.dependencyRecordError}`);
|
|
316
|
+
}
|
|
317
|
+
if (status.dependenciesOwner === "upstream-pm") {
|
|
318
|
+
console.log("note: upstream's package manager selects the dependency environment, not the npm package venv.");
|
|
319
|
+
} else if (status.upstreamSelfManagedStamp) {
|
|
320
|
+
console.log("note: the install stamp hands the checkout to upstream's package manager on its next launch.");
|
|
321
|
+
}
|
|
247
322
|
if (status.runtimeModifiedByNativeUpdate) {
|
|
248
323
|
console.log("note: npm reinstall/update will return the runtime to the latest release-pinned build.");
|
|
249
324
|
}
|
|
325
|
+
if (status.runtimeChannel === "missing") {
|
|
326
|
+
console.log("note: the runtime is not installed; run 'hermes-npm setup' (or start 'hermes', which sets it up on first launch).");
|
|
327
|
+
}
|
|
250
328
|
}
|
|
251
329
|
|
|
252
330
|
function getInstallMethods() {
|
|
@@ -257,9 +335,13 @@ function getInstallMethods() {
|
|
|
257
335
|
id: "npm-isolated",
|
|
258
336
|
install: "npm install --global hermes-agent",
|
|
259
337
|
projectInstall: "npm install hermes-agent",
|
|
338
|
+
npm12Install: "npm install --global --allow-scripts=hermes-agent hermes-agent",
|
|
339
|
+
npm12ProjectApproval: "npm install-scripts approve --no-allow-scripts-pin hermes-agent",
|
|
340
|
+
setup: "hermes-npm setup",
|
|
341
|
+
setupNote: "npm 12 blocks dependency install scripts by default; 'hermes-npm setup' or the first 'hermes' launch provisions the runtime instead",
|
|
260
342
|
commands: "hermes, hermes-agent, hermes-npm",
|
|
261
343
|
sourceLocation: "inside the installed npm package",
|
|
262
|
-
updateOwner: "hermes update (
|
|
344
|
+
updateOwner: "hermes-npm update (npm Release) or hermes update (native upstream updater, stable channel by default)",
|
|
263
345
|
uninstall: "npm uninstall --global hermes-agent",
|
|
264
346
|
projectUninstall: "npm uninstall hermes-agent"
|
|
265
347
|
},
|
|
@@ -295,7 +377,10 @@ function printMethods() {
|
|
|
295
377
|
npm-isolated (recommended when npm should own the deployment)
|
|
296
378
|
global: npm install --global hermes-agent
|
|
297
379
|
project: npm install hermes-agent
|
|
298
|
-
|
|
380
|
+
npm 12: install scripts are blocked by default; the first 'hermes'
|
|
381
|
+
launch or 'hermes-npm setup' provisions the runtime, or allow
|
|
382
|
+
the script: npm install --global --allow-scripts=hermes-agent hermes-agent
|
|
383
|
+
update: hermes-npm update (npm Release) or hermes update (native)
|
|
299
384
|
uninstall: matching global/project npm uninstall
|
|
300
385
|
|
|
301
386
|
upstream-managed (official source layout and native ownership)
|
|
@@ -320,12 +405,16 @@ function printHelp(topic) {
|
|
|
320
405
|
if (topic === "update") {
|
|
321
406
|
console.log(`Update commands
|
|
322
407
|
|
|
323
|
-
hermes update --check Check the upstream native rolling channel
|
|
324
|
-
hermes update Update the live checkout from upstream
|
|
325
408
|
hermes-npm check Check the npm Release channel
|
|
326
409
|
hermes-npm update Install/reset to the checked npm Release
|
|
327
|
-
|
|
328
|
-
|
|
410
|
+
hermes update --check Check the native upstream channel
|
|
411
|
+
hermes update Move the live checkout with the upstream updater
|
|
412
|
+
|
|
413
|
+
The native updater follows upstream's "stable" channel (GitHub Releases) by
|
|
414
|
+
default; 'hermes update --set-channel main' switches it to the rolling main
|
|
415
|
+
branch. Source moved by a native update is replaced by the next npm Release
|
|
416
|
+
update. With npm 12, 'hermes-npm update' provisions the new release itself
|
|
417
|
+
because npm skips the package install script.`);
|
|
329
418
|
return;
|
|
330
419
|
}
|
|
331
420
|
if (topic === "migrate") {
|
|
@@ -360,11 +449,12 @@ Commands:
|
|
|
360
449
|
status [--json] Show the npm release and live upstream runtime state
|
|
361
450
|
check [--json] Check the npm registry release channel
|
|
362
451
|
update Update through npm and return to the release channel
|
|
452
|
+
setup Install or repair the isolated runtime (alias: provision)
|
|
363
453
|
methods [--json] List supported installation and ownership models
|
|
364
454
|
migrate upstream Show a one-way handoff plan; add --yes to execute it
|
|
365
455
|
help [topic] Show help (install, update, migrate, uninstall)
|
|
366
456
|
|
|
367
|
-
The native
|
|
457
|
+
The native upstream updater remains available through 'hermes update'.
|
|
368
458
|
Run 'hermes-npm help install' before choosing a deployment model.`);
|
|
369
459
|
}
|
|
370
460
|
|
|
@@ -389,45 +479,101 @@ User configuration and state under HERMES_HOME are preserved. Stop gateways,
|
|
|
389
479
|
agents, and Desktop first. Re-run with '--yes' to execute this one-way handoff.`);
|
|
390
480
|
}
|
|
391
481
|
|
|
392
|
-
function
|
|
393
|
-
|
|
482
|
+
function getUpdatedPackageRoot(context, packageName = canonicalPackageName) {
|
|
483
|
+
if (context.isGlobal) return path.join(path.dirname(packageRoot), packageName);
|
|
484
|
+
return path.join(context.projectRoot || process.cwd(), "node_modules", packageName);
|
|
485
|
+
}
|
|
486
|
+
|
|
487
|
+
function readInstalledPackage(root) {
|
|
488
|
+
try {
|
|
489
|
+
return JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf8"));
|
|
490
|
+
} catch {
|
|
491
|
+
return null;
|
|
492
|
+
}
|
|
493
|
+
}
|
|
494
|
+
|
|
495
|
+
function installedRuntimeIsReady(root, installedPackage, platform = process.platform) {
|
|
496
|
+
const sourceDirectory = resolveRuntimeSourceDirectory(
|
|
497
|
+
root,
|
|
498
|
+
installedPackage.hermesAgent?.runtimeDirectory || "runtime/hermes-agent"
|
|
499
|
+
);
|
|
500
|
+
if (!fs.existsSync(venvConsoleExecutable(path.join(sourceDirectory, "venv"), "hermes", platform))) return false;
|
|
501
|
+
try {
|
|
502
|
+
const marker = JSON.parse(fs.readFileSync(path.join(root, ".hermes-agent-runtime.json"), "utf8"));
|
|
503
|
+
return marker.npmVersion === installedPackage.version;
|
|
504
|
+
} catch {
|
|
505
|
+
return false;
|
|
506
|
+
}
|
|
507
|
+
}
|
|
508
|
+
|
|
509
|
+
// npm <= 11 runs the new package's postinstall during 'npm install', so the
|
|
510
|
+
// runtime is already in place and this is a no-op. npm 12 blocks dependency
|
|
511
|
+
// install scripts by default and leaves only the shims, so run the freshly
|
|
512
|
+
// installed package's own installer directly. '--allow-scripts' is not used:
|
|
513
|
+
// npm 12 rejects that flag for project installs.
|
|
514
|
+
function ensureUpdatedRuntime(root, version, helpers = {}) {
|
|
515
|
+
const installedPackage = readInstalledPackage(root);
|
|
516
|
+
if (!installedPackage || installedPackage.version !== version) {
|
|
517
|
+
console.warn(
|
|
518
|
+
`npm finished, but ${canonicalPackageName}@${version} was not found at ${root}. ` +
|
|
519
|
+
"If 'hermes' reports that the runtime is not ready, run 'hermes-npm setup'."
|
|
520
|
+
);
|
|
521
|
+
return 0;
|
|
522
|
+
}
|
|
523
|
+
if (installedRuntimeIsReady(root, installedPackage)) return 0;
|
|
524
|
+
|
|
525
|
+
console.log("npm did not run the hermes-agent install script (npm 12 blocks dependency install scripts by default).");
|
|
526
|
+
console.log("Setting up the isolated runtime directly (one-time download, usually 1-2 minutes)...");
|
|
527
|
+
const result = (helpers.provisionRuntime || provisionRuntime)({
|
|
528
|
+
packageRoot: root,
|
|
529
|
+
postinstallScript: path.join(root, "scripts", "postinstall.js"),
|
|
530
|
+
isReady: () => installedRuntimeIsReady(root, installedPackage),
|
|
531
|
+
stdio: "inherit",
|
|
532
|
+
onWait: () => console.log("Waiting for another Hermes Agent setup to finish...")
|
|
533
|
+
});
|
|
534
|
+
if (result.error || result.status !== 0) {
|
|
535
|
+
console.error(`Runtime setup failed${result.error ? `: ${result.error}` : ` with exit code ${result.status}`}.`);
|
|
536
|
+
console.error("Retry with 'hermes-npm setup'.");
|
|
537
|
+
return result.status || 1;
|
|
538
|
+
}
|
|
539
|
+
return 0;
|
|
540
|
+
}
|
|
541
|
+
|
|
542
|
+
function applyReleaseUpdate(version, helpers = {}) {
|
|
543
|
+
const context = (helpers.detectInstallContext || detectInstallContext)();
|
|
394
544
|
assertReleaseUpdateAllowed(version, context);
|
|
395
|
-
const
|
|
396
|
-
const
|
|
545
|
+
const npm = getNpmSpawnSpec(getReleaseUpdateArgs(version, context));
|
|
546
|
+
const result = (helpers.spawnSync || spawnSync)(npm.command, npm.args, {
|
|
397
547
|
cwd: context.projectRoot || process.cwd(),
|
|
398
548
|
stdio: "inherit",
|
|
399
549
|
windowsHide: false
|
|
400
550
|
});
|
|
401
|
-
|
|
402
|
-
|
|
403
|
-
|
|
404
|
-
|
|
405
|
-
|
|
406
|
-
|
|
407
|
-
|
|
408
|
-
|
|
409
|
-
|
|
410
|
-
|
|
411
|
-
});
|
|
551
|
+
if (result.error) {
|
|
552
|
+
console.error(`Failed to start npm: ${result.error.message}`);
|
|
553
|
+
return 1;
|
|
554
|
+
}
|
|
555
|
+
if (result.signal) {
|
|
556
|
+
console.error(`npm was stopped by ${result.signal}.`);
|
|
557
|
+
return 1;
|
|
558
|
+
}
|
|
559
|
+
if (result.status !== 0) return result.status ?? 1;
|
|
560
|
+
return ensureUpdatedRuntime(getUpdatedPackageRoot(context), version, helpers);
|
|
412
561
|
}
|
|
413
562
|
|
|
414
|
-
function
|
|
415
|
-
const
|
|
416
|
-
|
|
563
|
+
function runSetup(helpers = {}) {
|
|
564
|
+
const result = (helpers.provisionRuntime || provisionRuntime)({
|
|
565
|
+
packageRoot: helpers.packageRoot || packageRoot,
|
|
566
|
+
args: helpers.args,
|
|
417
567
|
stdio: "inherit",
|
|
418
|
-
|
|
419
|
-
|
|
420
|
-
child.on("exit", (code, signal) => {
|
|
421
|
-
if (signal) {
|
|
422
|
-
process.kill(process.pid, signal);
|
|
423
|
-
return;
|
|
568
|
+
onWait: (lock) => {
|
|
569
|
+
console.log(`Waiting for another Hermes Agent setup to finish${lock?.pid ? ` (pid ${lock.pid})` : ""}...`);
|
|
424
570
|
}
|
|
425
|
-
process.exit(code ?? 1);
|
|
426
|
-
});
|
|
427
|
-
child.on("error", (error) => {
|
|
428
|
-
console.error(`Failed to reset the npm release runtime: ${error.message}`);
|
|
429
|
-
process.exit(1);
|
|
430
571
|
});
|
|
572
|
+
if (result.error) {
|
|
573
|
+
console.error(`Unable to set up the Hermes Agent runtime: ${result.error}`);
|
|
574
|
+
return result.status || 1;
|
|
575
|
+
}
|
|
576
|
+
return result.status;
|
|
431
577
|
}
|
|
432
578
|
|
|
433
579
|
async function runNpmChannel(args) {
|
|
@@ -482,6 +628,15 @@ async function runNpmChannel(args) {
|
|
|
482
628
|
}
|
|
483
629
|
return;
|
|
484
630
|
}
|
|
631
|
+
if (command === "setup" || command === "provision") {
|
|
632
|
+
if (args.length > 1) {
|
|
633
|
+
console.error(`Unknown setup option: ${args[1]}`);
|
|
634
|
+
process.exitCode = 2;
|
|
635
|
+
return;
|
|
636
|
+
}
|
|
637
|
+
process.exitCode = runSetup();
|
|
638
|
+
return;
|
|
639
|
+
}
|
|
485
640
|
if (command === "status") {
|
|
486
641
|
const status = readRuntimeStatus();
|
|
487
642
|
if (json) console.log(JSON.stringify(status, null, 2));
|
|
@@ -520,13 +675,13 @@ async function runNpmChannel(args) {
|
|
|
520
675
|
}
|
|
521
676
|
const comparison = compareSemver(latestVersion, packageJson.version);
|
|
522
677
|
if (comparison > 0) {
|
|
523
|
-
applyReleaseUpdate(latestVersion);
|
|
678
|
+
process.exitCode = applyReleaseUpdate(latestVersion);
|
|
524
679
|
} else {
|
|
525
680
|
const status = readRuntimeStatus();
|
|
526
681
|
if (status.runtimeChannel === "npm-release") {
|
|
527
682
|
console.log(`The npm release channel is already at ${packageJson.version}.`);
|
|
528
683
|
} else {
|
|
529
|
-
|
|
684
|
+
process.exitCode = runSetup({ args: ["--force-release"] });
|
|
530
685
|
}
|
|
531
686
|
}
|
|
532
687
|
} catch (error) {
|
|
@@ -543,18 +698,25 @@ async function runNpmChannel(args) {
|
|
|
543
698
|
|
|
544
699
|
module.exports = {
|
|
545
700
|
assertReleaseUpdateAllowed,
|
|
701
|
+
applyReleaseUpdate,
|
|
546
702
|
detectInstallContext,
|
|
547
703
|
compareSemver,
|
|
704
|
+
ensureUpdatedRuntime,
|
|
548
705
|
fetchLatestNpmVersion,
|
|
549
706
|
findNodeModulesOwner,
|
|
550
707
|
getAliasMigrationCommands,
|
|
551
708
|
getInstallMethods,
|
|
709
|
+
getNpmSpawnSpec,
|
|
552
710
|
getReleaseUpdateArgs,
|
|
553
711
|
getReleaseUpdateCommand,
|
|
712
|
+
getRuntimeChannel,
|
|
713
|
+
getUpdatedPackageRoot,
|
|
714
|
+
installedRuntimeIsReady,
|
|
554
715
|
isReleasePinned,
|
|
555
716
|
parseGitStatusPorcelain,
|
|
556
717
|
pathsReferToSameInstallLocation,
|
|
557
718
|
printHelp,
|
|
558
719
|
readRuntimeStatus,
|
|
559
|
-
runNpmChannel
|
|
720
|
+
runNpmChannel,
|
|
721
|
+
runSetup
|
|
560
722
|
};
|
package/lib/provision.js
ADDED
|
@@ -0,0 +1,177 @@
|
|
|
1
|
+
const { spawnSync } = require("node:child_process");
|
|
2
|
+
const fs = require("node:fs");
|
|
3
|
+
const path = require("node:path");
|
|
4
|
+
|
|
5
|
+
const LOCK_FILE_NAME = ".hermes-agent-provision.lock";
|
|
6
|
+
// Names the lock a parent already holds for the installer it spawned, so the
|
|
7
|
+
// child does not wait on its own parent.
|
|
8
|
+
const HELD_LOCK_ENV = "HERMES_NPM_PROVISION_LOCK";
|
|
9
|
+
// A lock whose PID is alive is honored: provisioning on a slow network can take
|
|
10
|
+
// well over an hour. Only a lock this old is treated as left over from a crash
|
|
11
|
+
// whose PID has since been reused.
|
|
12
|
+
const STALE_LOCK_MS = 6 * 60 * 60 * 1000;
|
|
13
|
+
// A lock file that cannot be parsed is only treated as stale after this grace
|
|
14
|
+
// period, so a holder that has created but not yet written it keeps the lock.
|
|
15
|
+
const UNREADABLE_LOCK_GRACE_MS = 30 * 1000;
|
|
16
|
+
const DEFAULT_WAIT_TIMEOUT_MS = 45 * 60 * 1000;
|
|
17
|
+
const WAIT_POLL_MS = 500;
|
|
18
|
+
|
|
19
|
+
function sleepSync(milliseconds) {
|
|
20
|
+
Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, milliseconds);
|
|
21
|
+
}
|
|
22
|
+
|
|
23
|
+
function processIsAlive(pid) {
|
|
24
|
+
if (!Number.isInteger(pid) || pid <= 0) return false;
|
|
25
|
+
try {
|
|
26
|
+
process.kill(pid, 0);
|
|
27
|
+
return true;
|
|
28
|
+
} catch (error) {
|
|
29
|
+
return error.code === "EPERM";
|
|
30
|
+
}
|
|
31
|
+
}
|
|
32
|
+
|
|
33
|
+
function getProvisionLockPath(packageRoot) {
|
|
34
|
+
return path.join(packageRoot, LOCK_FILE_NAME);
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
function readProvisionLock(lockPath) {
|
|
38
|
+
try {
|
|
39
|
+
const lock = JSON.parse(fs.readFileSync(lockPath, "utf8"));
|
|
40
|
+
return lock && typeof lock === "object" ? lock : null;
|
|
41
|
+
} catch {
|
|
42
|
+
return null;
|
|
43
|
+
}
|
|
44
|
+
}
|
|
45
|
+
|
|
46
|
+
function provisionLockIsStale(lockPath, now = Date.now(), isAlive = processIsAlive) {
|
|
47
|
+
let stats;
|
|
48
|
+
try {
|
|
49
|
+
stats = fs.statSync(lockPath);
|
|
50
|
+
} catch {
|
|
51
|
+
return false;
|
|
52
|
+
}
|
|
53
|
+
const lock = readProvisionLock(lockPath);
|
|
54
|
+
if (!lock) return now - stats.mtimeMs > UNREADABLE_LOCK_GRACE_MS;
|
|
55
|
+
const startedAt = Date.parse(lock.startedAt);
|
|
56
|
+
if (Number.isFinite(startedAt) && now - startedAt > STALE_LOCK_MS) return true;
|
|
57
|
+
return !isAlive(lock.pid);
|
|
58
|
+
}
|
|
59
|
+
|
|
60
|
+
function acquireProvisionLock(lockPath, options = {}) {
|
|
61
|
+
const timeoutMs = options.timeoutMs ?? DEFAULT_WAIT_TIMEOUT_MS;
|
|
62
|
+
const pollMs = options.pollMs ?? WAIT_POLL_MS;
|
|
63
|
+
const deadline = Date.now() + timeoutMs;
|
|
64
|
+
let waited = false;
|
|
65
|
+
|
|
66
|
+
while (true) {
|
|
67
|
+
try {
|
|
68
|
+
const fd = fs.openSync(lockPath, "wx");
|
|
69
|
+
try {
|
|
70
|
+
fs.writeSync(fd, `${JSON.stringify({ pid: process.pid, startedAt: new Date().toISOString() })}\n`);
|
|
71
|
+
} finally {
|
|
72
|
+
fs.closeSync(fd);
|
|
73
|
+
}
|
|
74
|
+
return { waited, release: () => releaseProvisionLock(lockPath) };
|
|
75
|
+
} catch (error) {
|
|
76
|
+
if (error.code !== "EEXIST") throw error;
|
|
77
|
+
}
|
|
78
|
+
|
|
79
|
+
if (provisionLockIsStale(lockPath)) {
|
|
80
|
+
fs.rmSync(lockPath, { force: true });
|
|
81
|
+
continue;
|
|
82
|
+
}
|
|
83
|
+
if (!waited) {
|
|
84
|
+
waited = true;
|
|
85
|
+
options.onWait?.(readProvisionLock(lockPath));
|
|
86
|
+
}
|
|
87
|
+
if (Date.now() >= deadline) {
|
|
88
|
+
throw new Error(`Timed out waiting for another Hermes Agent setup to finish (lock: ${lockPath})`);
|
|
89
|
+
}
|
|
90
|
+
sleepSync(pollMs);
|
|
91
|
+
}
|
|
92
|
+
}
|
|
93
|
+
|
|
94
|
+
function releaseProvisionLock(lockPath) {
|
|
95
|
+
const lock = readProvisionLock(lockPath);
|
|
96
|
+
if (lock && lock.pid !== process.pid) return;
|
|
97
|
+
fs.rmSync(lockPath, { force: true });
|
|
98
|
+
}
|
|
99
|
+
|
|
100
|
+
// Called by scripts/postinstall.js. A lifecycle run from npm takes the lock so a
|
|
101
|
+
// concurrent first launch waits for it instead of starting a second installer;
|
|
102
|
+
// a run spawned by provisionRuntime already holds it through its parent.
|
|
103
|
+
function holdProvisionLockForInstaller(packageRoot, options = {}) {
|
|
104
|
+
const lockPath = getProvisionLockPath(path.resolve(packageRoot));
|
|
105
|
+
const env = options.env || process.env;
|
|
106
|
+
if (env[HELD_LOCK_ENV] && path.resolve(env[HELD_LOCK_ENV]) === lockPath) {
|
|
107
|
+
return { waited: false, release() {} };
|
|
108
|
+
}
|
|
109
|
+
return acquireProvisionLock(lockPath, options);
|
|
110
|
+
}
|
|
111
|
+
|
|
112
|
+
function describeLockError(error, packageRoot) {
|
|
113
|
+
if (["EACCES", "EPERM", "EROFS"].includes(error.code)) {
|
|
114
|
+
return `Cannot write to the npm package directory ${packageRoot}. ` +
|
|
115
|
+
"Run 'hermes-npm setup' as the account that owns this npm installation " +
|
|
116
|
+
"(for a root-owned global prefix, with the same privileges used for 'npm install --global').";
|
|
117
|
+
}
|
|
118
|
+
return error.message;
|
|
119
|
+
}
|
|
120
|
+
|
|
121
|
+
// Runs the package's own scripts/postinstall.js under a lock in the package
|
|
122
|
+
// root. npm 12 blocks dependency install scripts by default, so the launcher,
|
|
123
|
+
// 'hermes-npm setup' and 'hermes-npm update' call this directly instead of
|
|
124
|
+
// relying on the npm lifecycle.
|
|
125
|
+
function provisionRuntime(options) {
|
|
126
|
+
const packageRoot = path.resolve(options.packageRoot);
|
|
127
|
+
const postinstallScript = options.postinstallScript || path.join(packageRoot, "scripts", "postinstall.js");
|
|
128
|
+
const lockPath = getProvisionLockPath(packageRoot);
|
|
129
|
+
const spawn = options.spawnSync || spawnSync;
|
|
130
|
+
|
|
131
|
+
let lock;
|
|
132
|
+
try {
|
|
133
|
+
lock = acquireProvisionLock(lockPath, {
|
|
134
|
+
onWait: options.onWait,
|
|
135
|
+
pollMs: options.pollMs,
|
|
136
|
+
timeoutMs: options.timeoutMs
|
|
137
|
+
});
|
|
138
|
+
} catch (error) {
|
|
139
|
+
return { status: 1, provisioned: false, error: describeLockError(error, packageRoot) };
|
|
140
|
+
}
|
|
141
|
+
|
|
142
|
+
try {
|
|
143
|
+
if (options.isReady?.()) {
|
|
144
|
+
return { status: 0, provisioned: false, waited: lock.waited };
|
|
145
|
+
}
|
|
146
|
+
options.onStart?.();
|
|
147
|
+
const result = spawn(process.execPath, [postinstallScript, ...(options.args || [])], {
|
|
148
|
+
cwd: packageRoot,
|
|
149
|
+
env: { ...(options.env || process.env), [HELD_LOCK_ENV]: lockPath },
|
|
150
|
+
stdio: options.stdio || "inherit",
|
|
151
|
+
windowsHide: true
|
|
152
|
+
});
|
|
153
|
+
if (result.error) {
|
|
154
|
+
return { status: 1, provisioned: true, error: `Unable to start the runtime installer: ${result.error.message}` };
|
|
155
|
+
}
|
|
156
|
+
if (result.signal) {
|
|
157
|
+
return { status: 1, provisioned: true, error: `The runtime installer was stopped by ${result.signal}` };
|
|
158
|
+
}
|
|
159
|
+
return { status: result.status ?? 1, provisioned: true, waited: lock.waited };
|
|
160
|
+
} finally {
|
|
161
|
+
lock.release();
|
|
162
|
+
}
|
|
163
|
+
}
|
|
164
|
+
|
|
165
|
+
module.exports = {
|
|
166
|
+
HELD_LOCK_ENV,
|
|
167
|
+
LOCK_FILE_NAME,
|
|
168
|
+
STALE_LOCK_MS,
|
|
169
|
+
acquireProvisionLock,
|
|
170
|
+
getProvisionLockPath,
|
|
171
|
+
holdProvisionLockForInstaller,
|
|
172
|
+
processIsAlive,
|
|
173
|
+
provisionLockIsStale,
|
|
174
|
+
provisionRuntime,
|
|
175
|
+
readProvisionLock,
|
|
176
|
+
releaseProvisionLock
|
|
177
|
+
};
|