@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.
Files changed (72) hide show
  1. package/README.md +29 -20
  2. package/dist/answers.d.ts +43 -0
  3. package/dist/answers.d.ts.map +1 -0
  4. package/dist/answers.js +744 -0
  5. package/dist/answers.js.map +1 -0
  6. package/dist/commandCatalog.d.ts +13 -1
  7. package/dist/commandCatalog.d.ts.map +1 -1
  8. package/dist/commandCatalog.js +65 -89
  9. package/dist/commandCatalog.js.map +1 -1
  10. package/dist/config.d.ts +5 -0
  11. package/dist/config.d.ts.map +1 -1
  12. package/dist/config.js +3 -1
  13. package/dist/config.js.map +1 -1
  14. package/dist/crossProfileCopy.d.ts +37 -0
  15. package/dist/crossProfileCopy.d.ts.map +1 -1
  16. package/dist/crossProfileCopy.js +77 -16
  17. package/dist/crossProfileCopy.js.map +1 -1
  18. package/dist/discovery.d.ts +8 -0
  19. package/dist/discovery.d.ts.map +1 -1
  20. package/dist/discovery.js +10 -0
  21. package/dist/discovery.js.map +1 -1
  22. package/dist/imageStore.d.ts +139 -0
  23. package/dist/imageStore.d.ts.map +1 -0
  24. package/dist/imageStore.js +385 -0
  25. package/dist/imageStore.js.map +1 -0
  26. package/dist/index.js +4 -4
  27. package/dist/index.js.map +1 -1
  28. package/dist/launcher.d.ts +64 -17
  29. package/dist/launcher.d.ts.map +1 -1
  30. package/dist/launcher.js +206 -167
  31. package/dist/launcher.js.map +1 -1
  32. package/dist/launcherCli.d.ts +13 -0
  33. package/dist/launcherCli.d.ts.map +1 -1
  34. package/dist/launcherCli.js +85 -91
  35. package/dist/launcherCli.js.map +1 -1
  36. package/dist/models.d.ts +117 -6
  37. package/dist/models.d.ts.map +1 -1
  38. package/dist/parser.d.ts +20 -7
  39. package/dist/parser.d.ts.map +1 -1
  40. package/dist/parser.js +48 -207
  41. package/dist/parser.js.map +1 -1
  42. package/dist/platform.d.ts +6 -0
  43. package/dist/platform.d.ts.map +1 -1
  44. package/dist/platform.js +14 -0
  45. package/dist/platform.js.map +1 -1
  46. package/dist/probe.d.ts +16 -0
  47. package/dist/probe.d.ts.map +1 -0
  48. package/dist/probe.js +31 -0
  49. package/dist/probe.js.map +1 -0
  50. package/dist/processTools.d.ts +22 -8
  51. package/dist/processTools.d.ts.map +1 -1
  52. package/dist/processTools.js +75 -58
  53. package/dist/processTools.js.map +1 -1
  54. package/dist/resultNormalizer.d.ts +9 -0
  55. package/dist/resultNormalizer.d.ts.map +1 -1
  56. package/dist/resultNormalizer.js +36 -79
  57. package/dist/resultNormalizer.js.map +1 -1
  58. package/dist/server.d.ts +10 -9
  59. package/dist/server.d.ts.map +1 -1
  60. package/dist/server.js +56 -55
  61. package/dist/server.js.map +1 -1
  62. package/dist/ston.d.ts +22 -0
  63. package/dist/ston.d.ts.map +1 -0
  64. package/dist/ston.js +127 -0
  65. package/dist/ston.js.map +1 -0
  66. package/docs/cleanup-hook-boundary.md +11 -9
  67. package/docs/development.md +51 -38
  68. package/docs/reference/tools.md +100 -40
  69. package/docs/troubleshooting.md +32 -23
  70. package/docs/user/getting-started.md +4 -4
  71. package/docs/user/profile-mode.md +30 -21
  72. package/package.json +1 -1
@@ -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 command result
41
- contains a startup diagnostic with the command, args, working directory, PATH,
42
- and active profile variables.
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 diagnostics report missing
86
- profile directories, missing configuration files, and failed probes.
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 verify the target image after the command exits. The MCP
91
- result is an error when the target image cannot be listed and inspected.
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
- Check:
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
- - the `createVerification` or `copyVerification` section
96
- - `raw.stdout` and `raw.stderr`
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
- The process must have a Pharo or Squeak command line that includes a `.image`
132
- path. For cleanup, prefer a PID captured from the detached launch result, which
133
- stops that process and nothing else. An `imageName` has to match the process's
134
- image name or image path exactly, so an image that is not listed by
135
- `pharo_launcher_process_list` under that exact name will not be found.
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. Timeout results include:
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 result is only successful when the new image can be listed and
146
- inspected after Launcher returns.
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
- If template listing still fails, inspect:
98
-
99
- ```text
100
- pharo_launcher_config
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
- All profile paths must be absolute. Image names must be launcher image names,
141
- not paths. Destination collisions are refused.
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 result reports source and destination image metadata, touched paths,
161
- metadata repair, verification, and cleanup guidance.
162
-
163
- A failure adds `message`, one line naming both images, both profiles, what went
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 command envelopes, log files,
173
- image names, image paths, process PIDs, and timeout reasons long enough to
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.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@evref-bl/pharo-launcher-mcp",
3
- "version": "0.4.0",
3
+ "version": "0.5.0",
4
4
  "description": "MCP server for controlling Pharo Launcher images, templates, VMs, and processes.",
5
5
  "license": "MIT",
6
6
  "type": "module",