@evref-bl/pharo-launcher-mcp 0.1.2 → 0.1.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.
Files changed (58) hide show
  1. package/README.md +229 -199
  2. package/bin/pharo-launcher.cmd +46 -46
  3. package/bin/pharo-launcher.sh +0 -0
  4. package/dist/commandCatalog.d.ts.map +1 -1
  5. package/dist/commandCatalog.js +23 -6
  6. package/dist/commandCatalog.js.map +1 -1
  7. package/dist/config.d.ts +21 -1
  8. package/dist/config.d.ts.map +1 -1
  9. package/dist/config.js +75 -6
  10. package/dist/config.js.map +1 -1
  11. package/dist/crossProfileCopy.d.ts +88 -0
  12. package/dist/crossProfileCopy.d.ts.map +1 -0
  13. package/dist/crossProfileCopy.js +511 -0
  14. package/dist/crossProfileCopy.js.map +1 -0
  15. package/dist/discovery.d.ts +165 -1
  16. package/dist/discovery.d.ts.map +1 -1
  17. package/dist/discovery.js +803 -3
  18. package/dist/discovery.js.map +1 -1
  19. package/dist/imageMetadata.d.ts +1 -0
  20. package/dist/imageMetadata.d.ts.map +1 -1
  21. package/dist/imageMetadata.js +35 -2
  22. package/dist/imageMetadata.js.map +1 -1
  23. package/dist/launcherCli.d.ts +2 -0
  24. package/dist/launcherCli.d.ts.map +1 -1
  25. package/dist/launcherCli.js +589 -62
  26. package/dist/launcherCli.js.map +1 -1
  27. package/dist/models.d.ts +3 -1
  28. package/dist/models.d.ts.map +1 -1
  29. package/dist/parser.d.ts.map +1 -1
  30. package/dist/parser.js +48 -13
  31. package/dist/parser.js.map +1 -1
  32. package/dist/platform.d.ts +2 -0
  33. package/dist/platform.d.ts.map +1 -1
  34. package/dist/platform.js +21 -0
  35. package/dist/platform.js.map +1 -1
  36. package/dist/processTools.d.ts.map +1 -1
  37. package/dist/processTools.js +13 -7
  38. package/dist/processTools.js.map +1 -1
  39. package/dist/resultNormalizer.d.ts +5 -1
  40. package/dist/resultNormalizer.d.ts.map +1 -1
  41. package/dist/resultNormalizer.js +79 -6
  42. package/dist/resultNormalizer.js.map +1 -1
  43. package/dist/server.d.ts +3 -0
  44. package/dist/server.d.ts.map +1 -1
  45. package/dist/server.js +475 -83
  46. package/dist/server.js.map +1 -1
  47. package/dist/textTokens.d.ts +10 -0
  48. package/dist/textTokens.d.ts.map +1 -0
  49. package/dist/textTokens.js +68 -0
  50. package/dist/textTokens.js.map +1 -0
  51. package/docs/README.md +26 -0
  52. package/docs/cleanup-hook-boundary.md +94 -0
  53. package/docs/development.md +59 -23
  54. package/docs/reference/tools.md +179 -0
  55. package/docs/troubleshooting.md +135 -0
  56. package/docs/user/getting-started.md +172 -0
  57. package/docs/user/profile-mode.md +183 -0
  58. package/package.json +59 -52
@@ -3,7 +3,10 @@ import fs from "node:fs";
3
3
  import path from "node:path";
4
4
  import { loadPharoLauncherConfig, } from "./config.js";
5
5
  import { resolveLauncherScript } from "./launcherScript.js";
6
+ import { compactTokenText } from "./textTokens.js";
7
+ import { parseLauncherOutput } from "./parser.js";
6
8
  import { shouldRunScriptThroughBash, shouldRunScriptThroughCommandShell, } from "./platform.js";
9
+ const POSIX_BASH_PATH_CANDIDATES = ["/bin/bash", "/usr/bin/bash"];
7
10
  function comparablePath(value) {
8
11
  const resolved = path.resolve(value);
9
12
  return process.platform === "win32" ? resolved.toLowerCase() : resolved;
@@ -36,6 +39,24 @@ function detachedLaunchLogPaths(config, args, startTime) {
36
39
  stderrPath: path.join(logsDir, `${baseName}.err.log`),
37
40
  };
38
41
  }
42
+ function launcherEnvironment(config) {
43
+ return {
44
+ ...process.env,
45
+ PHARO_LAUNCHER_IMAGE: config.launcherImage,
46
+ PHARO_LAUNCHER_VM: config.launcherVm,
47
+ ...(config.profile
48
+ ? {
49
+ PHARO_LAUNCHER_MCP_PROFILE: config.profile.name,
50
+ PHARO_LAUNCHER_MCP_STATE_ROOT: config.profile.stateRoot,
51
+ PHARO_LAUNCHER_MCP_IMAGES_DIR: config.profile.imagesDir,
52
+ PHARO_LAUNCHER_MCP_VMS_DIR: config.profile.vmsDir,
53
+ PHARO_LAUNCHER_MCP_TEMPLATE_SOURCES_DIR: config.profile.templateSourcesDir,
54
+ PHARO_LAUNCHER_MCP_INIT_SCRIPTS_DIR: config.profile.initScriptsDir,
55
+ PHARO_LAUNCHER_MCP_LOGS_DIR: config.profile.logsDir,
56
+ }
57
+ : {}),
58
+ };
59
+ }
39
60
  export function profileLauncherConfigurationContent(profile) {
40
61
  return [
41
62
  "PharoLauncherCLIConfiguration {",
@@ -48,26 +69,60 @@ export function profileLauncherConfigurationContent(profile) {
48
69
  "",
49
70
  ].join("\n");
50
71
  }
72
+ function changesPathForImage(imagePath) {
73
+ return /\.image$/i.test(imagePath)
74
+ ? imagePath.replace(/\.image$/i, ".changes")
75
+ : `${imagePath}.changes`;
76
+ }
77
+ function copyIfExists(source, destination) {
78
+ if (fs.existsSync(source) && !fs.existsSync(destination)) {
79
+ fs.copyFileSync(source, destination);
80
+ }
81
+ }
82
+ function ensureProfileLauncherImage(config, profileLauncherImage) {
83
+ const installationLauncherImage = path.resolve(config.installationLauncherImage);
84
+ if (!fs.existsSync(profileLauncherImage)) {
85
+ if (!fs.existsSync(installationLauncherImage)) {
86
+ throw new Error([
87
+ "Cannot bootstrap profile launcher image because the installation PharoLauncher image is missing.",
88
+ `source: ${installationLauncherImage}`,
89
+ `destination: ${profileLauncherImage}`,
90
+ ].join("\n"));
91
+ }
92
+ fs.copyFileSync(installationLauncherImage, profileLauncherImage);
93
+ }
94
+ copyIfExists(changesPathForImage(installationLauncherImage), changesPathForImage(profileLauncherImage));
95
+ }
51
96
  export function ensureProfileLauncherConfiguration(config) {
52
- if (!config.profile || !config.launcherConfiguration) {
97
+ if (!config.profile) {
53
98
  return;
54
99
  }
55
- const configurationPath = path.resolve(config.launcherConfiguration);
56
100
  const stateRoot = path.resolve(config.profile.stateRoot);
57
- if (!isPathInside(stateRoot, configurationPath)) {
101
+ const profileLauncherImage = path.resolve(config.profile.launcherImage);
102
+ if (!isPathInside(stateRoot, profileLauncherImage)) {
103
+ throw new Error(`Refusing launcher profile image outside PHARO_LAUNCHER_MCP_STATE_ROOT: ${profileLauncherImage}`);
104
+ }
105
+ const configurationPath = config.launcherConfiguration
106
+ ? path.resolve(config.launcherConfiguration)
107
+ : undefined;
108
+ if (configurationPath && !isPathInside(stateRoot, configurationPath)) {
58
109
  throw new Error(`Refusing launcher profile configuration outside PHARO_LAUNCHER_MCP_STATE_ROOT: ${configurationPath}`);
59
110
  }
60
111
  for (const directory of [
61
- path.dirname(config.profile.launcherImage),
112
+ path.dirname(profileLauncherImage),
62
113
  config.profile.imagesDir,
63
114
  config.profile.vmsDir,
64
115
  config.profile.templateSourcesDir,
65
116
  config.profile.initScriptsDir,
66
117
  config.profile.logsDir,
67
- path.dirname(configurationPath),
118
+ ...(configurationPath ? [path.dirname(configurationPath)] : []),
68
119
  ]) {
69
120
  fs.mkdirSync(directory, { recursive: true });
70
121
  }
122
+ ensureProfileLauncherImage(config, profileLauncherImage);
123
+ if (!configurationPath) {
124
+ return;
125
+ }
71
126
  const content = profileLauncherConfigurationContent(config.profile);
72
127
  if (!fs.existsSync(configurationPath) ||
73
128
  fs.readFileSync(configurationPath, "utf8") !== content) {
@@ -92,41 +147,90 @@ function scriptCommandAndArgs(scriptPath, args, platform, bashPath, comspec) {
92
147
  args: [...args],
93
148
  };
94
149
  }
150
+ function resolveBashPath(platform) {
151
+ if (platform === "win32") {
152
+ return "bash";
153
+ }
154
+ return (POSIX_BASH_PATH_CANDIDATES.find((candidate) => fs.existsSync(candidate)) ??
155
+ "bash");
156
+ }
157
+ function diagnosticProfileLines(env) {
158
+ return [
159
+ "PHARO_LAUNCHER_MCP_PROFILE",
160
+ "PHARO_LAUNCHER_MCP_STATE_ROOT",
161
+ "PHARO_LAUNCHER_MCP_IMAGES_DIR",
162
+ "PHARO_LAUNCHER_MCP_VMS_DIR",
163
+ "PHARO_LAUNCHER_MCP_TEMPLATE_SOURCES_DIR",
164
+ "PHARO_LAUNCHER_MCP_INIT_SCRIPTS_DIR",
165
+ "PHARO_LAUNCHER_MCP_LOGS_DIR",
166
+ ].flatMap((key) => {
167
+ const value = env[key];
168
+ return value ? [`${key}: ${value}`] : [];
169
+ });
170
+ }
171
+ export function launcherInvocationFailureDiagnostic(invocation, error) {
172
+ const pathValue = invocation.env.PATH ?? process.env.PATH ?? "";
173
+ return [
174
+ `Failed to start PharoLauncher CLI command: ${error.message}`,
175
+ `source: ${invocation.source}`,
176
+ `command: ${invocation.command}`,
177
+ `args: ${invocation.args.join(" ")}`,
178
+ `cwd: ${invocation.cwd}`,
179
+ `PATH: ${pathValue}`,
180
+ ...diagnosticProfileLines(invocation.env),
181
+ ].join("\n");
182
+ }
95
183
  export function isDetachedImageLaunch(args) {
96
184
  return (args[0] === "image" &&
97
185
  args[1] === "launch" &&
98
186
  args.includes("--detached"));
99
187
  }
188
+ function isImageLaunch(args) {
189
+ return args[0] === "image" && args[1] === "launch";
190
+ }
100
191
  export function launcherArgsForDetachedImageLaunch(args) {
101
192
  return args.filter((arg) => arg !== "--detached");
102
193
  }
194
+ function imageLaunchArgsAndDisplayMode(args, startTime) {
195
+ const displayModeIndex = args.indexOf("--displayMode");
196
+ if (displayModeIndex < 0) {
197
+ return { args: [...args], displayMode: "headless" };
198
+ }
199
+ const displayMode = args[displayModeIndex + 1];
200
+ if (displayMode !== "headless" && displayMode !== "interactive") {
201
+ return failedResult("Profile-scoped image launch displayMode must be headless or interactive.", startTime);
202
+ }
203
+ return {
204
+ args: args.filter((_arg, index) => index !== displayModeIndex && index !== displayModeIndex + 1),
205
+ displayMode,
206
+ };
207
+ }
208
+ function isImageCreateFromBuild(args) {
209
+ return args[0] === "image" && args[1] === "create" && args[2] === "fromBuild";
210
+ }
211
+ function profileScopedFromBuildDiagnostic(args, config) {
212
+ if (!config.profile || !isImageCreateFromBuild(args)) {
213
+ return undefined;
214
+ }
215
+ return [
216
+ "Refusing profile-scoped image create fromBuild before invoking Pharo Launcher.",
217
+ "Pharo Launcher currently applies the CLI profile imagesDirectory during creation, but fromBuild automatically launches the image without initializing PhLVirtualMachineManager from the CLI configuration.",
218
+ `That launch can download or run VMs outside PHARO_LAUNCHER_MCP_VMS_DIR (${config.profile.vmsDir}).`,
219
+ "Use a non-fromBuild creation path with explicit launch control, or fix Pharo Launcher to initialize the VM manager from the CLI configuration before fromBuild launch.",
220
+ ].join("\n");
221
+ }
103
222
  export function buildLauncherCliInvocation(args, config = loadPharoLauncherConfig(), options = {}) {
104
223
  const platform = options.platform ?? process.platform;
105
224
  const launcherArgs = config.launcherConfiguration
106
225
  ? ["--configuration", config.launcherConfiguration, ...args]
107
226
  : [...args];
108
- const env = {
109
- ...process.env,
110
- PHARO_LAUNCHER_IMAGE: config.launcherImage,
111
- PHARO_LAUNCHER_VM: config.launcherVm,
112
- ...(config.profile
113
- ? {
114
- PHARO_LAUNCHER_MCP_PROFILE: config.profile.name,
115
- PHARO_LAUNCHER_MCP_STATE_ROOT: config.profile.stateRoot,
116
- PHARO_LAUNCHER_MCP_IMAGES_DIR: config.profile.imagesDir,
117
- PHARO_LAUNCHER_MCP_VMS_DIR: config.profile.vmsDir,
118
- PHARO_LAUNCHER_MCP_TEMPLATE_SOURCES_DIR: config.profile.templateSourcesDir,
119
- PHARO_LAUNCHER_MCP_INIT_SCRIPTS_DIR: config.profile.initScriptsDir,
120
- PHARO_LAUNCHER_MCP_LOGS_DIR: config.profile.logsDir,
121
- }
122
- : {}),
123
- };
227
+ const env = launcherEnvironment(config);
124
228
  const launcherScript = config.launcherScript ??
125
229
  (options.resolveScript ?? ((value) => resolveLauncherScript({
126
230
  launcherDir: value.launcherDir,
127
231
  })))(config);
128
232
  if (launcherScript) {
129
- const commandAndArgs = scriptCommandAndArgs(launcherScript, launcherArgs, platform, options.bashPath, options.comspec ?? process.env.ComSpec);
233
+ const commandAndArgs = scriptCommandAndArgs(launcherScript, launcherArgs, platform, options.bashPath ?? resolveBashPath(platform), options.comspec ?? process.env.ComSpec);
130
234
  return {
131
235
  ...commandAndArgs,
132
236
  cwd: config.launcherDir,
@@ -149,6 +253,437 @@ export function buildLauncherCliInvocation(args, config = loadPharoLauncherConfi
149
253
  source: "direct",
150
254
  };
151
255
  }
256
+ function failedResult(stderr, startTime, extra = {}) {
257
+ return {
258
+ exitCode: 1,
259
+ stdout: "",
260
+ stderr,
261
+ durationMs: Date.now() - startTime,
262
+ timedOut: false,
263
+ ...extra,
264
+ };
265
+ }
266
+ function validateInvocationSetup(invocation, startTime) {
267
+ if (invocation.source !== "script" || !path.isAbsolute(invocation.command)) {
268
+ return undefined;
269
+ }
270
+ try {
271
+ fs.accessSync(invocation.command, fs.constants.X_OK);
272
+ return undefined;
273
+ }
274
+ catch (error) {
275
+ const message = error instanceof Error
276
+ ? `Selected launcher shell path is missing or inaccessible before spawn: ${error.message}`
277
+ : "Selected launcher shell path is missing or inaccessible before spawn";
278
+ return failedResult(launcherInvocationFailureDiagnostic(invocation, new Error(message)), startTime);
279
+ }
280
+ }
281
+ function trimForDiagnostic(value) {
282
+ const trimmed = value.trim();
283
+ return trimmed.length > 0 ? trimmed : undefined;
284
+ }
285
+ function commandFailureDiagnostic(label, result) {
286
+ return [
287
+ `${label} failed.`,
288
+ `exitCode: ${result.exitCode ?? "unknown"}`,
289
+ `timedOut: ${result.timedOut}`,
290
+ ...(result.timeoutReason ? [`timeoutReason: ${result.timeoutReason}`] : []),
291
+ ...(trimForDiagnostic(result.stdout)
292
+ ? [`stdout:\n${trimForDiagnostic(result.stdout)}`]
293
+ : []),
294
+ ...(trimForDiagnostic(result.stderr)
295
+ ? [`stderr:\n${trimForDiagnostic(result.stderr)}`]
296
+ : []),
297
+ ].join("\n");
298
+ }
299
+ function runInvocation(invocation, timeoutMs, startTime) {
300
+ return new Promise((resolve) => {
301
+ let child;
302
+ try {
303
+ child = spawn(invocation.command, invocation.args, {
304
+ cwd: invocation.cwd,
305
+ env: invocation.env,
306
+ windowsHide: true,
307
+ });
308
+ }
309
+ catch (error) {
310
+ resolve({
311
+ exitCode: null,
312
+ stdout: "",
313
+ stderr: launcherInvocationFailureDiagnostic(invocation, error instanceof Error ? error : new Error(String(error))),
314
+ durationMs: Date.now() - startTime,
315
+ timedOut: false,
316
+ });
317
+ return;
318
+ }
319
+ let stdout = "";
320
+ let stderr = "";
321
+ let timedOut = false;
322
+ let timeoutReason;
323
+ const stdoutStream = child.stdout;
324
+ const stderrStream = child.stderr;
325
+ if (!stdoutStream || !stderrStream) {
326
+ child.kill();
327
+ resolve({
328
+ exitCode: null,
329
+ stdout,
330
+ stderr: launcherInvocationFailureDiagnostic(invocation, new Error("PharoLauncher CLI spawn did not provide stdout/stderr streams")),
331
+ durationMs: Date.now() - startTime,
332
+ timedOut,
333
+ });
334
+ return;
335
+ }
336
+ const timeout = setTimeout(() => {
337
+ timedOut = true;
338
+ timeoutReason = `PharoLauncher CLI timed out after ${timeoutMs}ms`;
339
+ child.kill();
340
+ }, timeoutMs);
341
+ stdoutStream.setEncoding("utf8");
342
+ stderrStream.setEncoding("utf8");
343
+ stdoutStream.on("data", (chunk) => {
344
+ stdout += chunk;
345
+ });
346
+ stderrStream.on("data", (chunk) => {
347
+ stderr += chunk;
348
+ });
349
+ child.on("error", (error) => {
350
+ clearTimeout(timeout);
351
+ const errnoError = error;
352
+ resolve({
353
+ exitCode: null,
354
+ stdout,
355
+ stderr: launcherInvocationFailureDiagnostic(invocation, errnoError),
356
+ durationMs: Date.now() - startTime,
357
+ timedOut,
358
+ ...(timeoutReason ? { timeoutReason } : {}),
359
+ });
360
+ });
361
+ child.on("close", (exitCode) => {
362
+ clearTimeout(timeout);
363
+ resolve({
364
+ exitCode,
365
+ stdout,
366
+ stderr,
367
+ durationMs: Date.now() - startTime,
368
+ timedOut,
369
+ ...(timeoutReason ? { timeoutReason } : {}),
370
+ });
371
+ });
372
+ });
373
+ }
374
+ function parsedImagesFromInfo(stdout) {
375
+ const parsed = parseLauncherOutput("pharo_launcher_image_info", "ston", stdout);
376
+ if (parsed.status !== "parsed") {
377
+ return undefined;
378
+ }
379
+ if (Array.isArray(parsed.data)) {
380
+ return parsed.data.filter((item) => typeof item === "object" && item !== null);
381
+ }
382
+ if (typeof parsed.data === "object" && parsed.data !== null) {
383
+ return [parsed.data];
384
+ }
385
+ return undefined;
386
+ }
387
+ function imageNameFromLaunchArgs(args) {
388
+ const candidate = args.at(-1);
389
+ return candidate && !candidate.startsWith("--") ? candidate : undefined;
390
+ }
391
+ function scriptPathFromLaunchArgs(args) {
392
+ const scriptIndex = args.indexOf("--script");
393
+ return scriptIndex >= 0 ? args[scriptIndex + 1] : undefined;
394
+ }
395
+ function normalizePharoVersion(value) {
396
+ const trimmed = value.trim();
397
+ const numeric = trimmed.match(/^(\d{2,3})(?:\.(\d+))?$/);
398
+ if (!numeric) {
399
+ return trimmed;
400
+ }
401
+ const major = numeric[1];
402
+ const minor = numeric[2] ?? (major.length === 2 ? "0" : "");
403
+ return `${major}${minor}`;
404
+ }
405
+ function pharoVersionFromTemplate(image) {
406
+ const template = image.originTemplate;
407
+ const urlVersion = template?.url?.match(/(?:^|[/-])(\d{2,3})(?:[./-]|$)/)?.[1];
408
+ if (urlVersion) {
409
+ return normalizePharoVersion(urlVersion);
410
+ }
411
+ const nameVersion = template?.name?.match(/\b(?:Pharo|Moose)\D*(\d{2,3}(?:\.\d+)?)/i)?.[1];
412
+ return nameVersion ? normalizePharoVersion(nameVersion) : undefined;
413
+ }
414
+ function vmArchitectureSegment(image) {
415
+ const source = `${image.architecture ?? ""} ${image.originTemplate?.name ?? ""} ${image.originTemplate?.url ?? ""}`;
416
+ const lower = source.toLowerCase();
417
+ const compact = compactTokenText(source);
418
+ if (lower.includes("aarch64") || lower.includes("arm64")) {
419
+ return "aarch64";
420
+ }
421
+ if (lower.includes("x86") || compact.includes("32bit")) {
422
+ return "x86";
423
+ }
424
+ return "x64";
425
+ }
426
+ function imageVmId(image) {
427
+ if (image?.vmId) {
428
+ return image.vmId;
429
+ }
430
+ if (!image) {
431
+ return undefined;
432
+ }
433
+ const pharoVersion = image.pharoVersion ?? pharoVersionFromTemplate(image);
434
+ return pharoVersion
435
+ ? `${pharoVersion}-${vmArchitectureSegment(image)}`
436
+ : undefined;
437
+ }
438
+ function profileImagePath(profile, imageName, image) {
439
+ const imagePath = image?.imagePath ?? path.join(imageName, `${imageName}.image`);
440
+ return path.isAbsolute(imagePath)
441
+ ? path.resolve(imagePath)
442
+ : path.resolve(profile.imagesDir, imagePath);
443
+ }
444
+ function profileVmDirectory(profile, vmId) {
445
+ const vmDirectory = path.resolve(profile.vmsDir, vmId);
446
+ return isPathInside(profile.vmsDir, vmDirectory) ? vmDirectory : undefined;
447
+ }
448
+ function profileVmExecutableCandidates(vmDirectory) {
449
+ return [
450
+ path.join(vmDirectory, "Pharo.app", "Contents", "MacOS", "Pharo"),
451
+ path.join(vmDirectory, "Pharo.exe"),
452
+ path.join(vmDirectory, "PharoConsole.exe"),
453
+ path.join(vmDirectory, "pharo"),
454
+ path.join(vmDirectory, "pharo-vm", "pharo"),
455
+ ];
456
+ }
457
+ function looksLikeVmExecutable(filePath) {
458
+ return /^(?:Pharo|PharoConsole|pharo)(?:\.exe)?$/i.test(path.basename(filePath));
459
+ }
460
+ function scanForVmExecutable(vmDirectory) {
461
+ const stack = [vmDirectory];
462
+ let visited = 0;
463
+ while (stack.length > 0 && visited < 5_000) {
464
+ const current = stack.pop();
465
+ visited += 1;
466
+ let entries;
467
+ try {
468
+ entries = fs.readdirSync(current, { withFileTypes: true });
469
+ }
470
+ catch {
471
+ continue;
472
+ }
473
+ for (const entry of entries) {
474
+ const entryPath = path.join(current, entry.name);
475
+ if (entry.isDirectory()) {
476
+ stack.push(entryPath);
477
+ }
478
+ else if (entry.isFile() && looksLikeVmExecutable(entryPath)) {
479
+ return entryPath;
480
+ }
481
+ }
482
+ }
483
+ return undefined;
484
+ }
485
+ function resolveProfileVmExecutable(profile, vmId) {
486
+ const vmDirectory = profileVmDirectory(profile, vmId);
487
+ if (!vmDirectory) {
488
+ return undefined;
489
+ }
490
+ const knownCandidate = profileVmExecutableCandidates(vmDirectory).find((candidate) => isPathInside(profile.vmsDir, candidate) && fs.existsSync(candidate));
491
+ if (knownCandidate) {
492
+ return knownCandidate;
493
+ }
494
+ const scanned = scanForVmExecutable(vmDirectory);
495
+ return scanned && isPathInside(profile.vmsDir, scanned) ? scanned : undefined;
496
+ }
497
+ async function launcherCliSubcommand(args, config, timeoutMs) {
498
+ const invocation = buildLauncherCliInvocation(args, config);
499
+ return runInvocation(invocation, timeoutMs, Date.now());
500
+ }
501
+ function isLauncherCliResult(value) {
502
+ return "exitCode" in value;
503
+ }
504
+ function profileImageLaunchTarget(args, config, startTime) {
505
+ const profile = config.profile;
506
+ const imageName = imageNameFromLaunchArgs(args);
507
+ if (!profile || !imageName) {
508
+ return failedResult("Profile-scoped image launch could not determine the requested image name.", startTime);
509
+ }
510
+ return { profile, imageName };
511
+ }
512
+ async function inspectProfileImageForLaunch(target, config, timeoutMs, startTime) {
513
+ const infoArgs = ["image", "info", "--ston", target.imageName];
514
+ const infoResult = await launcherCliSubcommand(infoArgs, config, timeoutMs);
515
+ if (infoResult.exitCode !== 0 || infoResult.timedOut) {
516
+ return failedResult([
517
+ `Profile-scoped image launch could not inspect image ${target.imageName}.`,
518
+ commandFailureDiagnostic("pharo_launcher_image_info", infoResult),
519
+ ].join("\n"), startTime, {
520
+ timedOut: infoResult.timedOut,
521
+ ...(infoResult.timeoutReason
522
+ ? { timeoutReason: infoResult.timeoutReason }
523
+ : {}),
524
+ });
525
+ }
526
+ const images = parsedImagesFromInfo(infoResult.stdout);
527
+ const image = images?.find((candidate) => candidate.name === target.imageName) ??
528
+ images?.[0];
529
+ const imagePath = profileImagePath(target.profile, target.imageName, image);
530
+ if (!isPathInside(target.profile.imagesDir, imagePath)) {
531
+ return failedResult([
532
+ `Profile-scoped image launch refused image path outside PHARO_LAUNCHER_MCP_IMAGES_DIR (${target.profile.imagesDir}).`,
533
+ `image: ${imagePath}`,
534
+ ].join("\n"), startTime);
535
+ }
536
+ if (!fs.existsSync(imagePath)) {
537
+ return failedResult([
538
+ `Profile-scoped image launch could not find image file for ${target.imageName}.`,
539
+ `expected: ${imagePath}`,
540
+ ].join("\n"), startTime);
541
+ }
542
+ return { image, imagePath };
543
+ }
544
+ async function resolveProfileVmForLaunch(target, image, config, timeoutMs, startTime) {
545
+ const vmId = imageVmId(image);
546
+ if (!vmId) {
547
+ return failedResult(`Profile-scoped image launch could not determine a VM id for image ${target.imageName}.`, startTime);
548
+ }
549
+ let vmPath = resolveProfileVmExecutable(target.profile, vmId);
550
+ let vmUpdated = false;
551
+ if (!vmPath) {
552
+ const updateResult = await launcherCliSubcommand(["vm", "update", vmId], config, Math.max(timeoutMs, 120_000));
553
+ vmUpdated = updateResult.exitCode === 0 && !updateResult.timedOut;
554
+ if (!vmUpdated) {
555
+ return failedResult([
556
+ `Profile-scoped image launch could not install VM ${vmId} inside PHARO_LAUNCHER_MCP_VMS_DIR (${target.profile.vmsDir}).`,
557
+ commandFailureDiagnostic("pharo_launcher_vm_update", updateResult),
558
+ ].join("\n"), startTime, {
559
+ timedOut: updateResult.timedOut,
560
+ ...(updateResult.timeoutReason
561
+ ? { timeoutReason: updateResult.timeoutReason }
562
+ : {}),
563
+ });
564
+ }
565
+ vmPath = resolveProfileVmExecutable(target.profile, vmId);
566
+ }
567
+ if (!vmPath) {
568
+ return failedResult([
569
+ `Profile-scoped image launch could not resolve a profile-local VM executable for ${vmId} after VM update.`,
570
+ `PHARO_LAUNCHER_MCP_VMS_DIR: ${target.profile.vmsDir}`,
571
+ ].join("\n"), startTime);
572
+ }
573
+ return { vmId, vmPath, vmUpdated };
574
+ }
575
+ async function profileScopedImageLaunchPlan(args, config, timeoutMs, startTime, displayMode) {
576
+ const target = profileImageLaunchTarget(args, config, startTime);
577
+ if (isLauncherCliResult(target)) {
578
+ return target;
579
+ }
580
+ const inspection = await inspectProfileImageForLaunch(target, config, timeoutMs, startTime);
581
+ if (isLauncherCliResult(inspection)) {
582
+ return inspection;
583
+ }
584
+ const vm = await resolveProfileVmForLaunch(target, inspection.image, config, timeoutMs, startTime);
585
+ if (isLauncherCliResult(vm)) {
586
+ return vm;
587
+ }
588
+ const scriptPath = scriptPathFromLaunchArgs(args);
589
+ const invocationArgs = [
590
+ ...(displayMode === "headless" ? ["--headless"] : []),
591
+ inspection.imagePath,
592
+ ...(scriptPath ? ["eval", scriptPath] : []),
593
+ ];
594
+ return {
595
+ imageName: target.imageName,
596
+ imagePath: inspection.imagePath,
597
+ ...(scriptPath ? { scriptPath } : {}),
598
+ displayMode,
599
+ vmId: vm.vmId,
600
+ vmPath: vm.vmPath,
601
+ invocation: {
602
+ command: vm.vmPath,
603
+ args: invocationArgs,
604
+ cwd: path.dirname(inspection.imagePath),
605
+ env: launcherEnvironment(config),
606
+ source: "direct",
607
+ },
608
+ vmUpdated: vm.vmUpdated,
609
+ };
610
+ }
611
+ async function runDetachedProfileImageLaunch(plan, config, args, startTime) {
612
+ const logPaths = detachedLaunchLogPaths(config, args, startTime);
613
+ fs.mkdirSync(path.dirname(logPaths.stdoutPath), { recursive: true });
614
+ const stdoutFd = fs.openSync(logPaths.stdoutPath, "a");
615
+ let stderrFd;
616
+ try {
617
+ stderrFd = fs.openSync(logPaths.stderrPath, "a");
618
+ const child = spawn(plan.invocation.command, plan.invocation.args, {
619
+ cwd: plan.invocation.cwd,
620
+ env: plan.invocation.env,
621
+ detached: true,
622
+ stdio: ["ignore", stdoutFd, stderrFd],
623
+ windowsHide: true,
624
+ });
625
+ child.on("error", () => {
626
+ // Detached launches cannot report async spawn failures to the already
627
+ // returned result, but the listener prevents an unhandled error event.
628
+ });
629
+ child.unref();
630
+ return {
631
+ exitCode: 0,
632
+ stdout: [
633
+ `Detached profile-scoped Pharo image pid ${child.pid ?? "unknown"}.`,
634
+ `image: ${plan.imagePath}`,
635
+ `displayMode: ${plan.displayMode}`,
636
+ `vm: ${plan.vmPath}`,
637
+ `vmId: ${plan.vmId}`,
638
+ `vmUpdated: ${plan.vmUpdated}`,
639
+ `stdout: ${logPaths.stdoutPath}`,
640
+ `stderr: ${logPaths.stderrPath}`,
641
+ ].join("\n"),
642
+ stderr: "",
643
+ durationMs: Date.now() - startTime,
644
+ timedOut: false,
645
+ };
646
+ }
647
+ finally {
648
+ fs.closeSync(stdoutFd);
649
+ if (stderrFd !== undefined) {
650
+ fs.closeSync(stderrFd);
651
+ }
652
+ }
653
+ }
654
+ async function runProfileScopedImageLaunch(args, config, timeoutMs, startTime, detached, displayMode) {
655
+ ensureProfileLauncherConfiguration(config);
656
+ const plan = await profileScopedImageLaunchPlan(args, config, timeoutMs, startTime, displayMode);
657
+ if ("exitCode" in plan) {
658
+ return plan;
659
+ }
660
+ if (detached) {
661
+ const setupFailure = validateInvocationSetup(plan.invocation, startTime);
662
+ if (setupFailure) {
663
+ return setupFailure;
664
+ }
665
+ return runDetachedProfileImageLaunch(plan, config, args, startTime);
666
+ }
667
+ const setupFailure = validateInvocationSetup(plan.invocation, startTime);
668
+ if (setupFailure) {
669
+ return setupFailure;
670
+ }
671
+ const result = await runInvocation(plan.invocation, timeoutMs, startTime);
672
+ return {
673
+ ...result,
674
+ stdout: [
675
+ `Profile-scoped Pharo image launch.`,
676
+ `image: ${plan.imagePath}`,
677
+ `displayMode: ${plan.displayMode}`,
678
+ `vm: ${plan.vmPath}`,
679
+ `vmId: ${plan.vmId}`,
680
+ `vmUpdated: ${plan.vmUpdated}`,
681
+ result.stdout,
682
+ ]
683
+ .filter((line) => line.length > 0)
684
+ .join("\n"),
685
+ };
686
+ }
152
687
  export function runLauncherCli(args, options = {}) {
153
688
  const timeoutMs = options.timeoutMs ?? 30_000;
154
689
  const startTime = Date.now();
@@ -156,9 +691,35 @@ export function runLauncherCli(args, options = {}) {
156
691
  const invocationArgs = detachedImageLaunch
157
692
  ? launcherArgsForDetachedImageLaunch(args)
158
693
  : args;
694
+ const imageLaunchOptions = isImageLaunch(invocationArgs)
695
+ ? imageLaunchArgsAndDisplayMode(invocationArgs, startTime)
696
+ : { args: [...invocationArgs], displayMode: "headless" };
697
+ if ("exitCode" in imageLaunchOptions) {
698
+ return Promise.resolve(imageLaunchOptions);
699
+ }
700
+ const launcherArgs = imageLaunchOptions.args;
159
701
  const config = options.config ?? loadPharoLauncherConfig();
702
+ const scopedFromBuildDiagnostic = profileScopedFromBuildDiagnostic(launcherArgs, config);
703
+ if (scopedFromBuildDiagnostic) {
704
+ return Promise.resolve({
705
+ exitCode: 1,
706
+ stdout: "",
707
+ stderr: scopedFromBuildDiagnostic,
708
+ durationMs: Date.now() - startTime,
709
+ timedOut: false,
710
+ });
711
+ }
712
+ if (config.profile && isImageLaunch(launcherArgs)) {
713
+ return runProfileScopedImageLaunch(launcherArgs, config, timeoutMs, startTime, detachedImageLaunch, imageLaunchOptions.displayMode);
714
+ }
160
715
  ensureProfileLauncherConfiguration(config);
161
- const invocation = buildLauncherCliInvocation(invocationArgs, config);
716
+ const invocation = buildLauncherCliInvocation(launcherArgs, config, {
717
+ bashPath: options.bashPath,
718
+ });
719
+ const setupFailure = validateInvocationSetup(invocation, startTime);
720
+ if (setupFailure) {
721
+ return Promise.resolve(setupFailure);
722
+ }
162
723
  if (detachedImageLaunch) {
163
724
  const logPaths = detachedLaunchLogPaths(config, args, startTime);
164
725
  fs.mkdirSync(path.dirname(logPaths.stdoutPath), { recursive: true });
@@ -173,6 +734,10 @@ export function runLauncherCli(args, options = {}) {
173
734
  stdio: ["ignore", stdoutFd, stderrFd],
174
735
  windowsHide: true,
175
736
  });
737
+ child.on("error", () => {
738
+ // Detached launches cannot report async spawn failures to the already
739
+ // returned result, but the listener prevents an unhandled error event.
740
+ });
176
741
  child.unref();
177
742
  return Promise.resolve({
178
743
  exitCode: 0,
@@ -193,44 +758,6 @@ export function runLauncherCli(args, options = {}) {
193
758
  }
194
759
  }
195
760
  }
196
- return new Promise((resolve, reject) => {
197
- const child = spawn(invocation.command, invocation.args, {
198
- cwd: invocation.cwd,
199
- env: invocation.env,
200
- windowsHide: true,
201
- });
202
- let stdout = "";
203
- let stderr = "";
204
- let timedOut = false;
205
- let timeoutReason;
206
- const timeout = setTimeout(() => {
207
- timedOut = true;
208
- timeoutReason = `PharoLauncher CLI timed out after ${timeoutMs}ms`;
209
- child.kill();
210
- }, timeoutMs);
211
- child.stdout.setEncoding("utf8");
212
- child.stderr.setEncoding("utf8");
213
- child.stdout.on("data", (chunk) => {
214
- stdout += chunk;
215
- });
216
- child.stderr.on("data", (chunk) => {
217
- stderr += chunk;
218
- });
219
- child.on("error", (error) => {
220
- clearTimeout(timeout);
221
- reject(error);
222
- });
223
- child.on("close", (exitCode) => {
224
- clearTimeout(timeout);
225
- resolve({
226
- exitCode,
227
- stdout,
228
- stderr,
229
- durationMs: Date.now() - startTime,
230
- timedOut,
231
- ...(timeoutReason ? { timeoutReason } : {}),
232
- });
233
- });
234
- });
761
+ return runInvocation(invocation, timeoutMs, startTime);
235
762
  }
236
763
  //# sourceMappingURL=launcherCli.js.map