@evref-bl/pharo-launcher-mcp 0.2.0 → 0.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.
- package/README.md +42 -4
- package/dist/launcher.d.ts +123 -0
- package/dist/launcher.d.ts.map +1 -0
- package/dist/launcher.js +464 -0
- package/dist/launcher.js.map +1 -0
- package/dist/platform.d.ts +36 -0
- package/dist/platform.d.ts.map +1 -1
- package/dist/platform.js +47 -0
- package/dist/platform.js.map +1 -1
- package/dist/server.d.ts +5 -15
- package/dist/server.d.ts.map +1 -1
- package/dist/server.js +7 -377
- package/dist/server.js.map +1 -1
- package/docs/development.md +20 -19
- package/docs/troubleshooting.md +20 -0
- package/package.json +5 -5
package/README.md
CHANGED
|
@@ -36,8 +36,46 @@ npx @evref-bl/pharo-launcher-mcp
|
|
|
36
36
|
The package also provides the `pharo-launcher-mcp` executable when installed in
|
|
37
37
|
a project or globally.
|
|
38
38
|
|
|
39
|
-
|
|
40
|
-
|
|
39
|
+
## Use it as a library
|
|
40
|
+
|
|
41
|
+
A Node caller does not need the protocol. The tools are functions:
|
|
42
|
+
|
|
43
|
+
```js
|
|
44
|
+
import { openPharoLauncher } from "@evref-bl/pharo-launcher-mcp/launcher";
|
|
45
|
+
|
|
46
|
+
const launcher = openPharoLauncher();
|
|
47
|
+
const running = await launcher.listProcesses();
|
|
48
|
+
const images = await launcher.listImages({ nameFilter: "Task" });
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
Each call answers the normalized launcher result directly, with its `ok`,
|
|
52
|
+
`data`, `diagnostic` and `command` fields typed, rather than JSON inside an MCP
|
|
53
|
+
text block that the caller parses back.
|
|
54
|
+
|
|
55
|
+
A TypeScript caller gets those shapes with them, so a result does not have to
|
|
56
|
+
be described a second time on the way out:
|
|
57
|
+
|
|
58
|
+
```ts
|
|
59
|
+
import type {
|
|
60
|
+
LauncherCommandResult,
|
|
61
|
+
LauncherImage,
|
|
62
|
+
LauncherProcess,
|
|
63
|
+
LauncherTemplate,
|
|
64
|
+
} from "@evref-bl/pharo-launcher-mcp/launcher";
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
Scope is a config, not a process. A caller that works inside a profile passes
|
|
68
|
+
the environment that describes it, instead of spawning a process to hold those
|
|
69
|
+
variables:
|
|
70
|
+
|
|
71
|
+
```js
|
|
72
|
+
const scoped = openPharoLauncher({
|
|
73
|
+
env: { PHARO_LAUNCHER_MCP_PROFILE: "isolated", PHARO_LAUNCHER_MCP_STATE_ROOT: stateRoot },
|
|
74
|
+
});
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
The MCP server is an adapter over the same functions, so a host that embeds it
|
|
78
|
+
rather than spawning it imports that instead:
|
|
41
79
|
|
|
42
80
|
```js
|
|
43
81
|
import { callTool, createServer } from "@evref-bl/pharo-launcher-mcp";
|
|
@@ -45,8 +83,8 @@ import { loadPharoLauncherConfig } from "@evref-bl/pharo-launcher-mcp/config";
|
|
|
45
83
|
import { defaultLauncherDir } from "@evref-bl/pharo-launcher-mcp/platform";
|
|
46
84
|
```
|
|
47
85
|
|
|
48
|
-
|
|
49
|
-
|
|
86
|
+
The executable is reachable as a command, not as an import: loading it starts a
|
|
87
|
+
server on stdio.
|
|
50
88
|
|
|
51
89
|
## Terms
|
|
52
90
|
|
|
@@ -0,0 +1,123 @@
|
|
|
1
|
+
import { type PharoLauncherConfig } from "./config.js";
|
|
2
|
+
import { type LauncherCliRunner, type PharoLauncherConfigReport } from "./discovery.js";
|
|
3
|
+
import { copyImageBetweenProfiles } from "./crossProfileCopy.js";
|
|
4
|
+
/**
|
|
5
|
+
* The shapes these functions answer with.
|
|
6
|
+
*
|
|
7
|
+
* They are defined in the modules that produce them, and those modules are not
|
|
8
|
+
* subpaths, so until now a caller could invoke every function here and name
|
|
9
|
+
* none of its results. PLexus copied the template row into a type of its own
|
|
10
|
+
* and `pharo-agent` wrote it inline, and the two disagreed about whether a
|
|
11
|
+
* listed template carries `category` or `templateCategory` — a question no
|
|
12
|
+
* type could settle because none was reachable.
|
|
13
|
+
*
|
|
14
|
+
* `packageExports.test.ts` names them, so dropping one fails the typecheck.
|
|
15
|
+
*/
|
|
16
|
+
export type { LauncherCommandResult, LauncherImage, LauncherOutputFormat, LauncherProcess, LauncherTemplate, } from "./models.js";
|
|
17
|
+
export type { PharoLauncherConfigReport } from "./discovery.js";
|
|
18
|
+
export type { CrossProfileImageCopyResult } from "./crossProfileCopy.js";
|
|
19
|
+
import type { LauncherCommandResult, LauncherImage, LauncherProcess, LauncherTemplate } from "./models.js";
|
|
20
|
+
/** How a call reaches PharoLauncher, and what it is allowed to take. */
|
|
21
|
+
export interface PharoLauncherOptions {
|
|
22
|
+
config?: PharoLauncherConfig;
|
|
23
|
+
runner?: LauncherCliRunner;
|
|
24
|
+
timeoutMs?: number;
|
|
25
|
+
includeRaw?: boolean;
|
|
26
|
+
imageCopyVerificationTimeoutMs?: number;
|
|
27
|
+
imageCopyVerificationPollMs?: number;
|
|
28
|
+
sleep?: (milliseconds: number) => Promise<void>;
|
|
29
|
+
templateSourcesUrl?: string;
|
|
30
|
+
fetchTemplateSources?: (url: string) => Promise<string>;
|
|
31
|
+
}
|
|
32
|
+
/** The name the MCP adapter still uses for the same options. */
|
|
33
|
+
export type CallToolOptions = PharoLauncherOptions;
|
|
34
|
+
export declare function commandResultOptions(argumentsValue: unknown, options: PharoLauncherOptions): PharoLauncherOptions;
|
|
35
|
+
export declare function imageCopyResult(args: string[], options: PharoLauncherOptions): Promise<LauncherCommandResult>;
|
|
36
|
+
export declare function imageCreateResult(args: string[], options: PharoLauncherOptions): Promise<LauncherCommandResult>;
|
|
37
|
+
interface TemplateSourcesBootstrap {
|
|
38
|
+
ok: boolean;
|
|
39
|
+
action: "not_applicable" | "already_present" | "created" | "failed";
|
|
40
|
+
path?: string;
|
|
41
|
+
url?: string;
|
|
42
|
+
bytes?: number;
|
|
43
|
+
diagnostic?: string;
|
|
44
|
+
error?: string;
|
|
45
|
+
}
|
|
46
|
+
declare function ensureProfileTemplateSourcesBootstrap(config: PharoLauncherConfig | undefined, options: PharoLauncherOptions): Promise<TemplateSourcesBootstrap>;
|
|
47
|
+
/** What a template update reports beyond the command it ran. */
|
|
48
|
+
export interface TemplateUpdateResult extends LauncherCommandResult {
|
|
49
|
+
templateSourcesBootstrap?: Awaited<ReturnType<typeof ensureProfileTemplateSourcesBootstrap>>;
|
|
50
|
+
templateSourcesProbe?: LauncherCommandResult;
|
|
51
|
+
}
|
|
52
|
+
export declare function templateUpdateResult(args: string[], options: PharoLauncherOptions): Promise<TemplateUpdateResult>;
|
|
53
|
+
export declare function runCommand(toolName: string, args: string[], options: PharoLauncherOptions): Promise<LauncherCommandResult>;
|
|
54
|
+
/** Table shape, on every command that prints one. */
|
|
55
|
+
export interface LauncherTableOptions {
|
|
56
|
+
format?: "ston" | "text";
|
|
57
|
+
brief?: boolean;
|
|
58
|
+
rowMode?: boolean;
|
|
59
|
+
delimiter?: string;
|
|
60
|
+
includeRaw?: boolean;
|
|
61
|
+
}
|
|
62
|
+
export interface ImageCreateInput extends LauncherTableOptions {
|
|
63
|
+
templateName: string;
|
|
64
|
+
newImageName: string;
|
|
65
|
+
templateCategory?: string;
|
|
66
|
+
dev?: boolean;
|
|
67
|
+
noLaunch?: boolean;
|
|
68
|
+
}
|
|
69
|
+
export interface ImageStartInput extends LauncherTableOptions {
|
|
70
|
+
imageName: string;
|
|
71
|
+
script?: string;
|
|
72
|
+
detached?: boolean;
|
|
73
|
+
/** Profile mode only: PharoLauncher's own image launch has no display mode. */
|
|
74
|
+
displayMode?: "headless" | "interactive";
|
|
75
|
+
}
|
|
76
|
+
/**
|
|
77
|
+
* What this package does, named as what it does.
|
|
78
|
+
*
|
|
79
|
+
* Every call builds its arguments through the same catalog the MCP tools use,
|
|
80
|
+
* so the two cannot disagree about what `image create` takes. The types are
|
|
81
|
+
* the thing a caller gets here and does not get over a protocol.
|
|
82
|
+
*/
|
|
83
|
+
export interface PharoLauncher {
|
|
84
|
+
describeConfig(): PharoLauncherConfigReport;
|
|
85
|
+
listImages(input?: {
|
|
86
|
+
nameFilter?: string;
|
|
87
|
+
} & LauncherTableOptions): Promise<LauncherCommandResult<LauncherImage[]>>;
|
|
88
|
+
imageInfo(input: {
|
|
89
|
+
imageName: string;
|
|
90
|
+
} & LauncherTableOptions): Promise<LauncherCommandResult>;
|
|
91
|
+
createImage(input: ImageCreateInput): Promise<LauncherCommandResult>;
|
|
92
|
+
copyImage(input: {
|
|
93
|
+
imageName: string;
|
|
94
|
+
newImageName: string;
|
|
95
|
+
} & LauncherTableOptions): Promise<LauncherCommandResult>;
|
|
96
|
+
startImage(input: ImageStartInput): Promise<LauncherCommandResult>;
|
|
97
|
+
deleteImage(input: {
|
|
98
|
+
imageName: string;
|
|
99
|
+
force?: boolean;
|
|
100
|
+
} & LauncherTableOptions): Promise<LauncherCommandResult>;
|
|
101
|
+
listProcesses(input?: LauncherTableOptions): Promise<LauncherCommandResult<LauncherProcess[]>>;
|
|
102
|
+
killProcess(input: ({
|
|
103
|
+
pid: number | string;
|
|
104
|
+
} | {
|
|
105
|
+
imageName: string;
|
|
106
|
+
}) & LauncherTableOptions): Promise<LauncherCommandResult>;
|
|
107
|
+
listTemplateCategories(input?: LauncherTableOptions): Promise<LauncherCommandResult<string[]>>;
|
|
108
|
+
listTemplates(input?: {
|
|
109
|
+
templateCategory?: string;
|
|
110
|
+
} & LauncherTableOptions): Promise<LauncherCommandResult<LauncherTemplate[]>>;
|
|
111
|
+
updateTemplates(input?: LauncherTableOptions): Promise<TemplateUpdateResult>;
|
|
112
|
+
copyImageBetweenProfiles(input: unknown): ReturnType<typeof copyImageBetweenProfiles>;
|
|
113
|
+
}
|
|
114
|
+
export interface OpenPharoLauncherOptions extends PharoLauncherOptions {
|
|
115
|
+
/**
|
|
116
|
+
* Resolve the installation and the profile from this environment rather
|
|
117
|
+
* than from `process.env`, which is how a caller scopes a call to a profile
|
|
118
|
+
* without a process of its own.
|
|
119
|
+
*/
|
|
120
|
+
env?: NodeJS.ProcessEnv;
|
|
121
|
+
}
|
|
122
|
+
export declare function openPharoLauncher(options?: OpenPharoLauncherOptions): PharoLauncher;
|
|
123
|
+
//# sourceMappingURL=launcher.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"launcher.d.ts","sourceRoot":"","sources":["../src/launcher.ts"],"names":[],"mappings":"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"}
|
package/dist/launcher.js
ADDED
|
@@ -0,0 +1,464 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* What this package knows how to do, as functions.
|
|
3
|
+
*
|
|
4
|
+
* The tool list was the surface for as long as the only caller reached it over
|
|
5
|
+
* a protocol. It does not: PLexus is a Node program that already depends on
|
|
6
|
+
* this package, and no agent subscribes to these names — they reach the
|
|
7
|
+
* launcher through PLexus's own scoped tools. So the functions are the
|
|
8
|
+
* surface, and `server.ts` is an adapter that maps thirteen names onto them.
|
|
9
|
+
*
|
|
10
|
+
* Scope is a config, not a process. `loadPharoLauncherConfig` takes an
|
|
11
|
+
* environment object, so a caller that needs a profile passes one rather than
|
|
12
|
+
* spawning a process to hold `PHARO_LAUNCHER_*` variables.
|
|
13
|
+
*/
|
|
14
|
+
import fs from "node:fs";
|
|
15
|
+
import path from "node:path";
|
|
16
|
+
import { launcherModulePathBudget, launcherModulePathBudgetMessage, } from "./platform.js";
|
|
17
|
+
import { buildLauncherCommandArgs, ToolInputError, } from "./commandCatalog.js";
|
|
18
|
+
import { loadPharoLauncherConfig, } from "./config.js";
|
|
19
|
+
import { getPharoLauncherConfigReport, } from "./discovery.js";
|
|
20
|
+
import { buildLauncherCliInvocation, launcherInvocationFailureDiagnostic, runLauncherCli, } from "./launcherCli.js";
|
|
21
|
+
import { runNativeProcessTool, shouldUseNativeProcessTool, } from "./processTools.js";
|
|
22
|
+
import { repairCopiedImageMetadata } from "./imageMetadata.js";
|
|
23
|
+
import { normalizeLauncherResult } from "./resultNormalizer.js";
|
|
24
|
+
import { copyImageBetweenProfiles } from "./crossProfileCopy.js";
|
|
25
|
+
const defaultTemplateSourcesUrl = "https://files.pharo.org/pharo-launcher/sources.list";
|
|
26
|
+
const templateSourcesFileName = "sources.list";
|
|
27
|
+
const imageCopyVerificationTimeoutMs = 30_000;
|
|
28
|
+
const imageCopyVerificationPollMs = 1_000;
|
|
29
|
+
function runnerOptions(options) {
|
|
30
|
+
return {
|
|
31
|
+
...(options.config ? { config: options.config } : {}),
|
|
32
|
+
...(options.timeoutMs !== undefined ? { timeoutMs: options.timeoutMs } : {}),
|
|
33
|
+
};
|
|
34
|
+
}
|
|
35
|
+
function inputObject(input) {
|
|
36
|
+
if (!input || typeof input !== "object" || Array.isArray(input)) {
|
|
37
|
+
return {};
|
|
38
|
+
}
|
|
39
|
+
return input;
|
|
40
|
+
}
|
|
41
|
+
function optionalBoolean(input, key) {
|
|
42
|
+
const value = input[key];
|
|
43
|
+
if (value === undefined) {
|
|
44
|
+
return undefined;
|
|
45
|
+
}
|
|
46
|
+
if (typeof value !== "boolean") {
|
|
47
|
+
throw new ToolInputError(`${key} must be a boolean`);
|
|
48
|
+
}
|
|
49
|
+
return value;
|
|
50
|
+
}
|
|
51
|
+
export function commandResultOptions(argumentsValue, options) {
|
|
52
|
+
const includeRaw = optionalBoolean(inputObject(argumentsValue), "includeRaw");
|
|
53
|
+
return includeRaw === undefined ? options : { ...options, includeRaw };
|
|
54
|
+
}
|
|
55
|
+
function normalizeToolResult(toolName, args, result, options) {
|
|
56
|
+
return normalizeLauncherResult(toolName, args, result, {
|
|
57
|
+
includeRaw: options.includeRaw,
|
|
58
|
+
});
|
|
59
|
+
}
|
|
60
|
+
async function runLauncherToolCommand(runner, args, options) {
|
|
61
|
+
const startTime = Date.now();
|
|
62
|
+
try {
|
|
63
|
+
return await runner(args, runnerOptions(options));
|
|
64
|
+
}
|
|
65
|
+
catch (error) {
|
|
66
|
+
return {
|
|
67
|
+
exitCode: null,
|
|
68
|
+
stdout: "",
|
|
69
|
+
stderr: runnerExceptionDiagnostic(args, options, error),
|
|
70
|
+
durationMs: Date.now() - startTime,
|
|
71
|
+
timedOut: false,
|
|
72
|
+
};
|
|
73
|
+
}
|
|
74
|
+
}
|
|
75
|
+
function runnerExceptionDiagnostic(args, options, error) {
|
|
76
|
+
const normalizedError = error instanceof Error ? error : new Error(String(error));
|
|
77
|
+
try {
|
|
78
|
+
const invocation = buildLauncherCliInvocation(args, options.config ?? loadPharoLauncherConfig());
|
|
79
|
+
return launcherInvocationFailureDiagnostic(invocation, normalizedError);
|
|
80
|
+
}
|
|
81
|
+
catch (contextError) {
|
|
82
|
+
const contextMessage = contextError instanceof Error ? contextError.message : String(contextError);
|
|
83
|
+
return [
|
|
84
|
+
`Failed to start PharoLauncher CLI command: ${normalizedError.message}`,
|
|
85
|
+
`args: ${args.join(" ")}`,
|
|
86
|
+
`diagnosticContextError: ${contextMessage}`,
|
|
87
|
+
].join("\n");
|
|
88
|
+
}
|
|
89
|
+
}
|
|
90
|
+
function sleep(milliseconds) {
|
|
91
|
+
return new Promise((resolve) => setTimeout(resolve, milliseconds));
|
|
92
|
+
}
|
|
93
|
+
function imagesFromData(data) {
|
|
94
|
+
if (Array.isArray(data)) {
|
|
95
|
+
return data.filter((item) => typeof item === "object" && item !== null);
|
|
96
|
+
}
|
|
97
|
+
if (typeof data === "object" && data !== null) {
|
|
98
|
+
return [data];
|
|
99
|
+
}
|
|
100
|
+
return [];
|
|
101
|
+
}
|
|
102
|
+
function namedImage(data, imageName) {
|
|
103
|
+
return imagesFromData(data).find((image) => image.name === imageName);
|
|
104
|
+
}
|
|
105
|
+
async function inspectImageVerificationAttempt(runner, newImageName, operationLabel, options) {
|
|
106
|
+
const listArgs = buildLauncherCommandArgs("pharo_launcher_image_list", {
|
|
107
|
+
nameFilter: newImageName,
|
|
108
|
+
format: "ston",
|
|
109
|
+
});
|
|
110
|
+
const listResult = await runLauncherToolCommand(runner, listArgs ?? [], options);
|
|
111
|
+
const normalizedList = normalizeToolResult("pharo_launcher_image_list", listArgs ?? [], listResult, options);
|
|
112
|
+
const listedImage = normalizedList.ok
|
|
113
|
+
? namedImage(normalizedList.data, newImageName)
|
|
114
|
+
: undefined;
|
|
115
|
+
if (!normalizedList.ok || !listedImage) {
|
|
116
|
+
return {
|
|
117
|
+
list: normalizedList,
|
|
118
|
+
diagnostic: normalizedList.ok
|
|
119
|
+
? `${operationLabel} image did not appear in image list.`
|
|
120
|
+
: `Image list failed while verifying ${operationLabel.toLowerCase()} image.`,
|
|
121
|
+
};
|
|
122
|
+
}
|
|
123
|
+
const infoArgs = buildLauncherCommandArgs("pharo_launcher_image_info", {
|
|
124
|
+
imageName: newImageName,
|
|
125
|
+
format: "ston",
|
|
126
|
+
});
|
|
127
|
+
const infoResult = await runLauncherToolCommand(runner, infoArgs ?? [], options);
|
|
128
|
+
const normalizedInfo = normalizeToolResult("pharo_launcher_image_info", infoArgs ?? [], infoResult, options);
|
|
129
|
+
const inspectedImage = normalizedInfo.ok
|
|
130
|
+
? namedImage(normalizedInfo.data, newImageName)
|
|
131
|
+
: undefined;
|
|
132
|
+
return {
|
|
133
|
+
listedImage,
|
|
134
|
+
...(inspectedImage ? { inspectedImage } : {}),
|
|
135
|
+
list: normalizedList,
|
|
136
|
+
info: normalizedInfo,
|
|
137
|
+
// Only a failed attempt has something to report. The success path used to
|
|
138
|
+
// carry "image info failed" as well, unread by its one caller and wrong
|
|
139
|
+
// for anyone who read it next.
|
|
140
|
+
...(inspectedImage
|
|
141
|
+
? {}
|
|
142
|
+
: {
|
|
143
|
+
diagnostic: normalizedInfo.ok
|
|
144
|
+
? `${operationLabel} image appeared in image list but could not be inspected.`
|
|
145
|
+
: `${operationLabel} image appeared in image list, but image info failed.`,
|
|
146
|
+
}),
|
|
147
|
+
};
|
|
148
|
+
}
|
|
149
|
+
async function verifyImage(runner, newImageName, operationLabel, options) {
|
|
150
|
+
const startedAt = Date.now();
|
|
151
|
+
const deadline = startedAt +
|
|
152
|
+
(options.imageCopyVerificationTimeoutMs ?? imageCopyVerificationTimeoutMs);
|
|
153
|
+
const pollMs = options.imageCopyVerificationPollMs ?? imageCopyVerificationPollMs;
|
|
154
|
+
const wait = options.sleep ?? sleep;
|
|
155
|
+
let attempts = 0;
|
|
156
|
+
let lastList;
|
|
157
|
+
let lastInfo;
|
|
158
|
+
let diagnostic = `${operationLabel} image did not appear in image list.`;
|
|
159
|
+
while (true) {
|
|
160
|
+
attempts += 1;
|
|
161
|
+
const attempt = await inspectImageVerificationAttempt(runner, newImageName, operationLabel, options);
|
|
162
|
+
lastList = attempt.list;
|
|
163
|
+
lastInfo = attempt.info;
|
|
164
|
+
if (attempt.listedImage && attempt.inspectedImage) {
|
|
165
|
+
return {
|
|
166
|
+
ok: true,
|
|
167
|
+
targetImageName: newImageName,
|
|
168
|
+
attempts,
|
|
169
|
+
elapsedMs: Date.now() - startedAt,
|
|
170
|
+
listedImage: attempt.listedImage,
|
|
171
|
+
inspectedImage: attempt.inspectedImage,
|
|
172
|
+
list: attempt.list,
|
|
173
|
+
...(attempt.info ? { info: attempt.info } : {}),
|
|
174
|
+
};
|
|
175
|
+
}
|
|
176
|
+
diagnostic = attempt.diagnostic ?? diagnostic;
|
|
177
|
+
const remainingMs = deadline - Date.now();
|
|
178
|
+
if (remainingMs <= 0) {
|
|
179
|
+
break;
|
|
180
|
+
}
|
|
181
|
+
await wait(Math.min(pollMs, remainingMs));
|
|
182
|
+
}
|
|
183
|
+
return {
|
|
184
|
+
ok: false,
|
|
185
|
+
targetImageName: newImageName,
|
|
186
|
+
attempts,
|
|
187
|
+
elapsedMs: Date.now() - startedAt,
|
|
188
|
+
diagnostic,
|
|
189
|
+
...(lastList ? { list: lastList } : {}),
|
|
190
|
+
...(lastInfo ? { info: lastInfo } : {}),
|
|
191
|
+
};
|
|
192
|
+
}
|
|
193
|
+
export async function imageCopyResult(args, options) {
|
|
194
|
+
const runner = options.runner ?? runLauncherCli;
|
|
195
|
+
const result = await runLauncherToolCommand(runner, args, options);
|
|
196
|
+
const normalized = normalizeToolResult("pharo_launcher_image_copy", args, result, options);
|
|
197
|
+
const newImageName = args[3];
|
|
198
|
+
if (!normalized.ok || !newImageName) {
|
|
199
|
+
return normalized;
|
|
200
|
+
}
|
|
201
|
+
const metadataRepair = repairCopiedImageMetadata(options.config ?? loadPharoLauncherConfig(), args[2], newImageName);
|
|
202
|
+
const verification = await verifyImage(runner, newImageName, "Copied", options);
|
|
203
|
+
const copyResult = {
|
|
204
|
+
...normalized,
|
|
205
|
+
ok: verification.ok,
|
|
206
|
+
...(verification.ok
|
|
207
|
+
? {
|
|
208
|
+
data: {
|
|
209
|
+
...(typeof normalized.data === "object" && normalized.data !== null
|
|
210
|
+
? normalized.data
|
|
211
|
+
: {}),
|
|
212
|
+
targetImageName: newImageName,
|
|
213
|
+
listedImage: verification.listedImage,
|
|
214
|
+
inspectedImage: verification.inspectedImage,
|
|
215
|
+
},
|
|
216
|
+
}
|
|
217
|
+
: {}),
|
|
218
|
+
metadataRepair,
|
|
219
|
+
...(!verification.ok
|
|
220
|
+
? {
|
|
221
|
+
diagnostic: `Image copy command exited successfully, but target image ${newImageName} was not listable and inspectable: ${verification.diagnostic}`,
|
|
222
|
+
}
|
|
223
|
+
: {}),
|
|
224
|
+
copyVerification: verification,
|
|
225
|
+
};
|
|
226
|
+
return copyResult;
|
|
227
|
+
}
|
|
228
|
+
export async function imageCreateResult(args, options) {
|
|
229
|
+
const runner = options.runner ?? runLauncherCli;
|
|
230
|
+
const result = await runLauncherToolCommand(runner, args, options);
|
|
231
|
+
const normalized = normalizeToolResult("pharo_launcher_image_create", args, result, options);
|
|
232
|
+
const newImageName = args.at(-1);
|
|
233
|
+
if (!normalized.ok || !newImageName) {
|
|
234
|
+
return normalized;
|
|
235
|
+
}
|
|
236
|
+
const verification = await verifyImage(runner, newImageName, "Created", options);
|
|
237
|
+
const createResult = {
|
|
238
|
+
...normalized,
|
|
239
|
+
ok: verification.ok,
|
|
240
|
+
...(verification.ok
|
|
241
|
+
? {
|
|
242
|
+
data: {
|
|
243
|
+
...(typeof normalized.data === "object" && normalized.data !== null
|
|
244
|
+
? normalized.data
|
|
245
|
+
: {}),
|
|
246
|
+
targetImageName: newImageName,
|
|
247
|
+
listedImage: verification.listedImage,
|
|
248
|
+
inspectedImage: verification.inspectedImage,
|
|
249
|
+
createdImage: verification.inspectedImage,
|
|
250
|
+
},
|
|
251
|
+
}
|
|
252
|
+
: {}),
|
|
253
|
+
...(!verification.ok
|
|
254
|
+
? {
|
|
255
|
+
diagnostic: `Image create command exited successfully, but target image ${newImageName} was not listable and inspectable: ${verification.diagnostic}`,
|
|
256
|
+
}
|
|
257
|
+
: {}),
|
|
258
|
+
createVerification: verification,
|
|
259
|
+
};
|
|
260
|
+
return createResult;
|
|
261
|
+
}
|
|
262
|
+
function profileTemplateSourcesFile(config) {
|
|
263
|
+
return config?.profile
|
|
264
|
+
? path.join(config.profile.templateSourcesDir, templateSourcesFileName)
|
|
265
|
+
: undefined;
|
|
266
|
+
}
|
|
267
|
+
function nonEmptyFile(filePath) {
|
|
268
|
+
try {
|
|
269
|
+
const stat = fs.statSync(filePath);
|
|
270
|
+
return stat.isFile() && stat.size > 0;
|
|
271
|
+
}
|
|
272
|
+
catch {
|
|
273
|
+
return false;
|
|
274
|
+
}
|
|
275
|
+
}
|
|
276
|
+
async function defaultFetchTemplateSources(url) {
|
|
277
|
+
const response = await fetch(url);
|
|
278
|
+
if (!response.ok) {
|
|
279
|
+
throw new Error(`HTTP ${response.status} ${response.statusText}`.trim());
|
|
280
|
+
}
|
|
281
|
+
return response.text();
|
|
282
|
+
}
|
|
283
|
+
async function ensureProfileTemplateSourcesBootstrap(config, options) {
|
|
284
|
+
const sourcesPath = profileTemplateSourcesFile(config);
|
|
285
|
+
if (!sourcesPath) {
|
|
286
|
+
return { ok: true, action: "not_applicable" };
|
|
287
|
+
}
|
|
288
|
+
if (nonEmptyFile(sourcesPath)) {
|
|
289
|
+
return {
|
|
290
|
+
ok: true,
|
|
291
|
+
action: "already_present",
|
|
292
|
+
path: sourcesPath,
|
|
293
|
+
bytes: fs.statSync(sourcesPath).size,
|
|
294
|
+
};
|
|
295
|
+
}
|
|
296
|
+
const url = options.templateSourcesUrl ?? defaultTemplateSourcesUrl;
|
|
297
|
+
try {
|
|
298
|
+
const fetchTemplateSources = options.fetchTemplateSources ?? defaultFetchTemplateSources;
|
|
299
|
+
const body = await fetchTemplateSources(url);
|
|
300
|
+
if (body.trim().length === 0) {
|
|
301
|
+
throw new Error("downloaded template source list was empty");
|
|
302
|
+
}
|
|
303
|
+
fs.mkdirSync(path.dirname(sourcesPath), { recursive: true });
|
|
304
|
+
const tempPath = `${sourcesPath}.${process.pid}.${Date.now()}.tmp`;
|
|
305
|
+
fs.writeFileSync(tempPath, body, "utf8");
|
|
306
|
+
fs.renameSync(tempPath, sourcesPath);
|
|
307
|
+
return {
|
|
308
|
+
ok: true,
|
|
309
|
+
action: "created",
|
|
310
|
+
path: sourcesPath,
|
|
311
|
+
url,
|
|
312
|
+
bytes: Buffer.byteLength(body, "utf8"),
|
|
313
|
+
};
|
|
314
|
+
}
|
|
315
|
+
catch (error) {
|
|
316
|
+
const message = error instanceof Error ? error.message : String(error);
|
|
317
|
+
return {
|
|
318
|
+
ok: false,
|
|
319
|
+
action: "failed",
|
|
320
|
+
path: sourcesPath,
|
|
321
|
+
url,
|
|
322
|
+
diagnostic: "Pharo Launcher template update completed, but the active profile template source bootstrap file is missing or empty.",
|
|
323
|
+
error: message,
|
|
324
|
+
};
|
|
325
|
+
}
|
|
326
|
+
}
|
|
327
|
+
export async function templateUpdateResult(args, options) {
|
|
328
|
+
const runner = options.runner ?? runLauncherCli;
|
|
329
|
+
const config = options.config ?? loadPharoLauncherConfig();
|
|
330
|
+
const commandOptions = {
|
|
331
|
+
...options,
|
|
332
|
+
config,
|
|
333
|
+
};
|
|
334
|
+
const result = await runLauncherToolCommand(runner, args, commandOptions);
|
|
335
|
+
const normalized = normalizeToolResult("pharo_launcher_template_update", args, result, commandOptions);
|
|
336
|
+
if (!normalized.ok) {
|
|
337
|
+
return normalized;
|
|
338
|
+
}
|
|
339
|
+
const bootstrap = await ensureProfileTemplateSourcesBootstrap(config, commandOptions);
|
|
340
|
+
if (!bootstrap.ok) {
|
|
341
|
+
return {
|
|
342
|
+
...normalized,
|
|
343
|
+
ok: false,
|
|
344
|
+
diagnostic: bootstrap.diagnostic,
|
|
345
|
+
action: "Fetch or seed the active profile sources.list, then run pharo_launcher_template_update again before planning image creation.",
|
|
346
|
+
templateSourcesBootstrap: bootstrap,
|
|
347
|
+
};
|
|
348
|
+
}
|
|
349
|
+
if (bootstrap.action === "not_applicable") {
|
|
350
|
+
return {
|
|
351
|
+
...normalized,
|
|
352
|
+
templateSourcesBootstrap: bootstrap,
|
|
353
|
+
};
|
|
354
|
+
}
|
|
355
|
+
const probeArgs = ["template", "list", "--ston"];
|
|
356
|
+
const probeResult = normalizeToolResult("pharo_launcher_template_list", probeArgs, await runLauncherToolCommand(runner, probeArgs, commandOptions), commandOptions);
|
|
357
|
+
if (!probeResult.ok) {
|
|
358
|
+
return {
|
|
359
|
+
...normalized,
|
|
360
|
+
ok: false,
|
|
361
|
+
diagnostic: probeResult.diagnostic ??
|
|
362
|
+
"Pharo Launcher template update completed, but template list still failed for the active profile.",
|
|
363
|
+
action: probeResult.action ??
|
|
364
|
+
"Inspect pharo_launcher_template_list diagnostics before planning image creation.",
|
|
365
|
+
templateSourcesBootstrap: bootstrap,
|
|
366
|
+
templateSourcesProbe: probeResult,
|
|
367
|
+
};
|
|
368
|
+
}
|
|
369
|
+
return {
|
|
370
|
+
...normalized,
|
|
371
|
+
templateSourcesBootstrap: bootstrap,
|
|
372
|
+
templateSourcesProbe: probeResult,
|
|
373
|
+
};
|
|
374
|
+
}
|
|
375
|
+
export async function runCommand(toolName, args, options) {
|
|
376
|
+
if (toolName === "pharo_launcher_image_copy") {
|
|
377
|
+
return imageCopyResult(args, options);
|
|
378
|
+
}
|
|
379
|
+
if (toolName === "pharo_launcher_image_create") {
|
|
380
|
+
return imageCreateResult(args, options);
|
|
381
|
+
}
|
|
382
|
+
if (toolName === "pharo_launcher_template_update") {
|
|
383
|
+
return templateUpdateResult(args, options);
|
|
384
|
+
}
|
|
385
|
+
const runner = options.runner ?? runLauncherCli;
|
|
386
|
+
const result = toolName.startsWith("pharo_launcher_process_") && shouldUseNativeProcessTool()
|
|
387
|
+
? await runNativeProcessTool(args, options.timeoutMs)
|
|
388
|
+
: await runLauncherToolCommand(runner, args, options);
|
|
389
|
+
return normalizeToolResult(toolName, args, result, options);
|
|
390
|
+
}
|
|
391
|
+
/** The longest path anything under this directory already has. */
|
|
392
|
+
function longestDescendantLength(directory) {
|
|
393
|
+
if (!fs.existsSync(directory)) {
|
|
394
|
+
return undefined;
|
|
395
|
+
}
|
|
396
|
+
let longest = 0;
|
|
397
|
+
const walk = (dir) => {
|
|
398
|
+
for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
|
|
399
|
+
const full = path.join(dir, entry.name);
|
|
400
|
+
if (entry.isDirectory()) {
|
|
401
|
+
walk(full);
|
|
402
|
+
}
|
|
403
|
+
else {
|
|
404
|
+
longest = Math.max(longest, full.length);
|
|
405
|
+
}
|
|
406
|
+
}
|
|
407
|
+
};
|
|
408
|
+
walk(directory);
|
|
409
|
+
return longest === 0 ? undefined : longest;
|
|
410
|
+
}
|
|
411
|
+
/**
|
|
412
|
+
* Refuse to start an image the VM could not load its own modules for.
|
|
413
|
+
*
|
|
414
|
+
* Starting it anyway reports a missing symbol in a file that is present and
|
|
415
|
+
* correct, which is a long way from the profile root being too deep.
|
|
416
|
+
*/
|
|
417
|
+
function assertLauncherModulePathsFit(config) {
|
|
418
|
+
// Resolved the way runCommand resolves it: a launcher opened with no
|
|
419
|
+
// arguments has no config until a call loads one, and the profile this
|
|
420
|
+
// check is about lives in it.
|
|
421
|
+
const vmsDirectory = (config ?? loadPharoLauncherConfig())?.profile?.vmsDir;
|
|
422
|
+
if (vmsDirectory === undefined) {
|
|
423
|
+
return;
|
|
424
|
+
}
|
|
425
|
+
const budget = launcherModulePathBudget(vmsDirectory, longestDescendantLength);
|
|
426
|
+
if (!budget.ok) {
|
|
427
|
+
throw new ToolInputError(launcherModulePathBudgetMessage(budget));
|
|
428
|
+
}
|
|
429
|
+
}
|
|
430
|
+
export function openPharoLauncher(options = {}) {
|
|
431
|
+
const { env, ...rest } = options;
|
|
432
|
+
const config = options.config ??
|
|
433
|
+
(env ? loadPharoLauncherConfig({ ...process.env, ...env }) : undefined);
|
|
434
|
+
const resolved = {
|
|
435
|
+
...rest,
|
|
436
|
+
...(config ? { config } : {}),
|
|
437
|
+
};
|
|
438
|
+
async function command(toolName, input) {
|
|
439
|
+
const args = buildLauncherCommandArgs(toolName, input ?? {});
|
|
440
|
+
if (!args) {
|
|
441
|
+
throw new ToolInputError(`Unknown launcher command: ${toolName}`);
|
|
442
|
+
}
|
|
443
|
+
return (await runCommand(toolName, args, commandResultOptions(input ?? {}, resolved)));
|
|
444
|
+
}
|
|
445
|
+
return {
|
|
446
|
+
describeConfig: () => getPharoLauncherConfigReport(resolved.config),
|
|
447
|
+
listImages: (input) => command("pharo_launcher_image_list", input),
|
|
448
|
+
imageInfo: (input) => command("pharo_launcher_image_info", input),
|
|
449
|
+
createImage: (input) => command("pharo_launcher_image_create", input),
|
|
450
|
+
copyImage: (input) => command("pharo_launcher_image_copy", input),
|
|
451
|
+
startImage: (input) => {
|
|
452
|
+
assertLauncherModulePathsFit(resolved.config);
|
|
453
|
+
return command("pharo_launcher_image_start", input);
|
|
454
|
+
},
|
|
455
|
+
deleteImage: (input) => command("pharo_launcher_image_delete", input),
|
|
456
|
+
listProcesses: (input) => command("pharo_launcher_process_list", input),
|
|
457
|
+
killProcess: (input) => command("pharo_launcher_process_kill", input),
|
|
458
|
+
listTemplateCategories: (input) => command("pharo_launcher_template_category_list", input),
|
|
459
|
+
listTemplates: (input) => command("pharo_launcher_template_list", input),
|
|
460
|
+
updateTemplates: (input) => command("pharo_launcher_template_update", input),
|
|
461
|
+
copyImageBetweenProfiles: (input) => copyImageBetweenProfiles(input),
|
|
462
|
+
};
|
|
463
|
+
}
|
|
464
|
+
//# sourceMappingURL=launcher.js.map
|