@evref-bl/pharo-launcher-mcp 0.4.0 → 0.5.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 +29 -20
- package/dist/answers.d.ts +43 -0
- package/dist/answers.d.ts.map +1 -0
- package/dist/answers.js +744 -0
- package/dist/answers.js.map +1 -0
- package/dist/commandCatalog.d.ts +13 -1
- package/dist/commandCatalog.d.ts.map +1 -1
- package/dist/commandCatalog.js +65 -89
- package/dist/commandCatalog.js.map +1 -1
- package/dist/config.d.ts +5 -0
- package/dist/config.d.ts.map +1 -1
- package/dist/config.js +3 -1
- package/dist/config.js.map +1 -1
- package/dist/crossProfileCopy.d.ts +37 -0
- package/dist/crossProfileCopy.d.ts.map +1 -1
- package/dist/crossProfileCopy.js +77 -16
- package/dist/crossProfileCopy.js.map +1 -1
- package/dist/discovery.d.ts +8 -0
- package/dist/discovery.d.ts.map +1 -1
- package/dist/discovery.js +10 -0
- package/dist/discovery.js.map +1 -1
- package/dist/imageStore.d.ts +139 -0
- package/dist/imageStore.d.ts.map +1 -0
- package/dist/imageStore.js +385 -0
- package/dist/imageStore.js.map +1 -0
- package/dist/index.js +4 -4
- package/dist/index.js.map +1 -1
- package/dist/launcher.d.ts +64 -17
- package/dist/launcher.d.ts.map +1 -1
- package/dist/launcher.js +206 -167
- package/dist/launcher.js.map +1 -1
- package/dist/launcherCli.d.ts +13 -0
- package/dist/launcherCli.d.ts.map +1 -1
- package/dist/launcherCli.js +85 -91
- package/dist/launcherCli.js.map +1 -1
- package/dist/models.d.ts +117 -6
- package/dist/models.d.ts.map +1 -1
- package/dist/parser.d.ts +20 -7
- package/dist/parser.d.ts.map +1 -1
- package/dist/parser.js +48 -207
- package/dist/parser.js.map +1 -1
- package/dist/platform.d.ts +6 -0
- package/dist/platform.d.ts.map +1 -1
- package/dist/platform.js +14 -0
- package/dist/platform.js.map +1 -1
- package/dist/probe.d.ts +16 -0
- package/dist/probe.d.ts.map +1 -0
- package/dist/probe.js +31 -0
- package/dist/probe.js.map +1 -0
- package/dist/processTools.d.ts +22 -8
- package/dist/processTools.d.ts.map +1 -1
- package/dist/processTools.js +75 -58
- package/dist/processTools.js.map +1 -1
- package/dist/resultNormalizer.d.ts +9 -0
- package/dist/resultNormalizer.d.ts.map +1 -1
- package/dist/resultNormalizer.js +36 -79
- package/dist/resultNormalizer.js.map +1 -1
- package/dist/server.d.ts +10 -9
- package/dist/server.d.ts.map +1 -1
- package/dist/server.js +56 -55
- package/dist/server.js.map +1 -1
- package/dist/ston.d.ts +22 -0
- package/dist/ston.d.ts.map +1 -0
- package/dist/ston.js +127 -0
- package/dist/ston.js.map +1 -0
- package/docs/cleanup-hook-boundary.md +11 -9
- package/docs/development.md +51 -38
- package/docs/reference/tools.md +100 -40
- package/docs/troubleshooting.md +32 -23
- package/docs/user/getting-started.md +4 -4
- package/docs/user/profile-mode.md +30 -21
- package/package.json +1 -1
package/docs/troubleshooting.md
CHANGED
|
@@ -37,9 +37,9 @@ selected discovery source and all attempted candidates.
|
|
|
37
37
|
bundled wrapper for the host platform. If that wrapper cannot be resolved, the
|
|
38
38
|
server invokes the VM directly with the Launcher control image.
|
|
39
39
|
|
|
40
|
-
If a selected wrapper path exists but is not executable, the
|
|
41
|
-
|
|
42
|
-
|
|
40
|
+
If a selected wrapper path exists but is not executable, the tool answers a
|
|
41
|
+
startup diagnostic with the command, args, working directory, PATH, and active
|
|
42
|
+
profile variables.
|
|
43
43
|
|
|
44
44
|
## Installation Validation Fails
|
|
45
45
|
|
|
@@ -82,24 +82,26 @@ pharo_launcher_template_list
|
|
|
82
82
|
```
|
|
83
83
|
|
|
84
84
|
`template_update` seeds the active profile source list when Launcher leaves it
|
|
85
|
-
missing or empty, then probes `template list`. Its
|
|
86
|
-
|
|
85
|
+
missing or empty, then probes `template list`. Its answer says when the
|
|
86
|
+
download of the source list or the probe failed. Until it ran once, a profile
|
|
87
|
+
has no template sources, and `template_list` and `image_create` say so.
|
|
87
88
|
|
|
88
89
|
## Image Create Or Copy Reports An Error After Launcher Succeeds
|
|
89
90
|
|
|
90
|
-
Create and copy tools
|
|
91
|
-
|
|
91
|
+
Create and copy tools check, for up to 30 s after the command, that the Launcher
|
|
92
|
+
can list the new image and open it. The answer is an error when it cannot, and
|
|
93
|
+
says which check failed:
|
|
92
94
|
|
|
93
|
-
|
|
95
|
+
- `Pharo Launcher said it created X, but <images>/X does not exist after 30 s`,
|
|
96
|
+
or names the file `<images>/X` lacks: the images directory holds no image
|
|
97
|
+
named exactly `X`, which holds `X.image` and `X.changes`. Check that the
|
|
98
|
+
active profile, or the Launcher's settings outside a profile, point at the
|
|
99
|
+
images directory `pharo_launcher_config` prints.
|
|
100
|
+
- `Pharo Launcher made X but cannot open it: …`: the Launcher's own
|
|
101
|
+
`image info X` failed, with its message.
|
|
94
102
|
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
- whether the image name already existed
|
|
98
|
-
- whether the active profile points at the expected images directory
|
|
99
|
-
- whether the Launcher template source list is valid
|
|
100
|
-
|
|
101
|
-
For copied images, the result also reports metadata repair and inspected image
|
|
102
|
-
metadata when available.
|
|
103
|
+
A Launcher that refused the command answers its own message: a name already
|
|
104
|
+
used, or a template or category it does not know.
|
|
103
105
|
|
|
104
106
|
## Image Start Is Refused Because The VM Directory Is Too Deep
|
|
105
107
|
|
|
@@ -128,20 +130,27 @@ Process tools use native host process queries:
|
|
|
128
130
|
- Windows: PowerShell/CIM
|
|
129
131
|
- macOS and Linux: `ps -axo pid=,args=`
|
|
130
132
|
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
133
|
+
They see only the VMs running an image of this Launcher's images directory: a
|
|
134
|
+
process whose command line names `<images>/D/D.image`, the path spelled as the
|
|
135
|
+
images directory is or as its real path. A VM of another Launcher, of another
|
|
136
|
+
profile, or given its image by a relative path is not listed and cannot be
|
|
137
|
+
killed through the server. For cleanup, prefer a PID captured from the detached
|
|
138
|
+
launch result, which stops that process and nothing else. An `imageName` finds
|
|
139
|
+
the image as the other tools do, exactly, else ignoring case.
|
|
136
140
|
|
|
137
141
|
## Commands Time Out
|
|
138
142
|
|
|
139
|
-
Every Launcher command is bounded by a timeout
|
|
143
|
+
Every Launcher command is bounded by a timeout, and the tool answers that Pharo
|
|
144
|
+
Launcher did not finish within it. The library's result says so with:
|
|
140
145
|
|
|
141
146
|
- `command.timedOut: true`
|
|
142
147
|
- `command.timeoutReason`
|
|
143
148
|
- command args
|
|
144
|
-
- raw stdout/stderr captured before the timeout
|
|
149
|
+
- raw stdout/stderr captured before the timeout, with `includeRaw`
|
|
150
|
+
|
|
151
|
+
A create or copy that outlived the timeout is still checked: when its image is
|
|
152
|
+
there, the call succeeds with a warning, and the library's `command.timedOut`
|
|
153
|
+
stays true.
|
|
145
154
|
|
|
146
155
|
A timeout does not authorize broader host cleanup. Cleanup should use only
|
|
147
156
|
recorded image names, profile roots, and PIDs that the caller owns.
|
|
@@ -136,14 +136,14 @@ Then create an image with an explicit name:
|
|
|
136
136
|
"tool": "pharo_launcher_image_create",
|
|
137
137
|
"arguments": {
|
|
138
138
|
"templateName": "Pharo 13.0 - 64bit",
|
|
139
|
-
"newImageName": "sample-130"
|
|
140
|
-
"noLaunch": true
|
|
139
|
+
"newImageName": "sample-130"
|
|
141
140
|
}
|
|
142
141
|
}
|
|
143
142
|
```
|
|
144
143
|
|
|
145
|
-
The create
|
|
146
|
-
|
|
144
|
+
The create answer is only successful when Launcher can list the new image and
|
|
145
|
+
open it after it returns. Creating does not start the image:
|
|
146
|
+
`pharo_launcher_image_start` does.
|
|
147
147
|
|
|
148
148
|
## No-Profile Defaults
|
|
149
149
|
|
|
@@ -94,14 +94,10 @@ template source file after Launcher returns. If the source file is missing or
|
|
|
94
94
|
empty, the server seeds it from the default Pharo Launcher source list and then
|
|
95
95
|
probes `template list`.
|
|
96
96
|
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
```
|
|
102
|
-
|
|
103
|
-
Its report includes missing or unreadable profile directories and
|
|
104
|
-
configuration files.
|
|
97
|
+
Its answer says when downloading the source list or the probe failed. Until the
|
|
98
|
+
profile has a source list, `pharo_launcher_template_list` and
|
|
99
|
+
`pharo_launcher_image_create` answer that there are no templates yet, and to
|
|
100
|
+
call `pharo_launcher_template_update` first.
|
|
105
101
|
|
|
106
102
|
## Image Launch In Profile Mode
|
|
107
103
|
|
|
@@ -133,12 +129,18 @@ profile.
|
|
|
133
129
|
|
|
134
130
|
Both `sourceProfile` and `destinationProfile` must include either:
|
|
135
131
|
|
|
136
|
-
- `stateRoot`, or
|
|
132
|
+
- `stateRoot`, the directory that holds the profile's `images/` directory, or
|
|
137
133
|
- the complete explicit path set: `launcherConfiguration`, `imagesDir`,
|
|
138
134
|
`vmsDir`, `templateSourcesDir`, `initScriptsDir`, and `logsDir`.
|
|
139
135
|
|
|
140
|
-
|
|
141
|
-
|
|
136
|
+
`pharo_launcher_config` prints the active profile's `stateRoot`. Given a
|
|
137
|
+
`stateRoot`, every other path defaults to its place in the layout above, and is
|
|
138
|
+
given only for a profile that keeps it elsewhere.
|
|
139
|
+
|
|
140
|
+
All profile paths must be absolute, and must exist: the copy creates none. A
|
|
141
|
+
`stateRoot` that does not exist or holds no `images/` directory, and any path
|
|
142
|
+
given that does not exist, is refused and named. Image names must be launcher
|
|
143
|
+
image names, not paths. Destination collisions are refused.
|
|
142
144
|
|
|
143
145
|
Example:
|
|
144
146
|
|
|
@@ -157,21 +159,28 @@ Example:
|
|
|
157
159
|
}
|
|
158
160
|
```
|
|
159
161
|
|
|
160
|
-
The
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
wrong and the way out, next to the `diagnostic` and `action` it is built from.
|
|
165
|
-
A destination that already exists is named by its directory, so the caller can
|
|
166
|
-
read `destinationImage`, adopt what is there, copy under another name, or
|
|
162
|
+
The tool answers one line naming the image and both profiles, each by its
|
|
163
|
+
`stateRoot` (or its `imagesDir` when it has none), then the copy's path. A
|
|
164
|
+
failure says what went wrong and the way out. A destination
|
|
165
|
+
that already exists is named by its directory: copy under another name, or
|
|
167
166
|
delete it with the destination profile active. An existing image is never
|
|
168
167
|
replaced.
|
|
169
168
|
|
|
169
|
+
The library's `copyImageBetweenProfiles` answers the full result, as before:
|
|
170
|
+
source and destination image metadata, touched paths, metadata repair,
|
|
171
|
+
verification, and cleanup guidance. A failure adds `failure`, which names what
|
|
172
|
+
went wrong (`profile-path-missing`, `source-missing`, `source-image-missing`,
|
|
173
|
+
`source-metadata-missing`, `destination-exists`, `preflight`, `post-move` or
|
|
174
|
+
`exception`), and `message`, one line naming both images and both profiles,
|
|
175
|
+
next to the `diagnostic` and `action` it is built from. With
|
|
176
|
+
`profile-path-missing`, `missingProfilePaths` names each path that does not
|
|
177
|
+
exist, by profile and field.
|
|
178
|
+
|
|
170
179
|
## Cleanup Rules
|
|
171
180
|
|
|
172
|
-
Only clean up caller-owned profile state. Keep
|
|
173
|
-
image names, image paths, process PIDs, and timeout reasons long enough
|
|
174
|
-
debug failed runs.
|
|
181
|
+
Only clean up caller-owned profile state. Keep the library's results, log
|
|
182
|
+
files, image names, image paths, process PIDs, and timeout reasons long enough
|
|
183
|
+
to debug failed runs.
|
|
175
184
|
|
|
176
185
|
For process cleanup, prefer a recorded PID from a detached launch. For image
|
|
177
186
|
cleanup, delete only image names created by the caller in the active profile.
|