@evref-bl/pharo-launcher-mcp 0.1.1 → 0.1.3
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 +158 -123
- package/bin/pharo-launcher.cmd +46 -46
- package/bin/pharo-launcher.sh +0 -0
- package/dist/commandCatalog.d.ts.map +1 -1
- package/dist/commandCatalog.js +17 -0
- package/dist/commandCatalog.js.map +1 -1
- package/dist/config.d.ts +21 -1
- package/dist/config.d.ts.map +1 -1
- package/dist/config.js +97 -11
- package/dist/config.js.map +1 -1
- package/dist/crossProfileCopy.d.ts +87 -0
- package/dist/crossProfileCopy.d.ts.map +1 -0
- package/dist/crossProfileCopy.js +437 -0
- package/dist/crossProfileCopy.js.map +1 -0
- package/dist/discovery.d.ts +165 -1
- package/dist/discovery.d.ts.map +1 -1
- package/dist/discovery.js +744 -1
- package/dist/discovery.js.map +1 -1
- package/dist/imageMetadata.d.ts +9 -0
- package/dist/imageMetadata.d.ts.map +1 -0
- package/dist/imageMetadata.js +82 -0
- package/dist/imageMetadata.js.map +1 -0
- package/dist/launcherCli.d.ts +7 -1
- package/dist/launcherCli.d.ts.map +1 -1
- package/dist/launcherCli.js +651 -32
- package/dist/launcherCli.js.map +1 -1
- package/dist/models.d.ts +2 -0
- package/dist/models.d.ts.map +1 -1
- package/dist/platform.d.ts +2 -0
- package/dist/platform.d.ts.map +1 -1
- package/dist/platform.js +21 -0
- package/dist/platform.js.map +1 -1
- package/dist/resultNormalizer.d.ts.map +1 -1
- package/dist/resultNormalizer.js +87 -1
- package/dist/resultNormalizer.js.map +1 -1
- package/dist/server.d.ts +6 -1
- package/dist/server.d.ts.map +1 -1
- package/dist/server.js +516 -6
- package/dist/server.js.map +1 -1
- package/docs/README.md +26 -0
- package/docs/cleanup-hook-boundary.md +94 -0
- package/docs/development.md +64 -22
- package/docs/reference/tools.md +179 -0
- package/docs/troubleshooting.md +135 -0
- package/docs/user/getting-started.md +172 -0
- package/docs/user/profile-mode.md +176 -0
- package/package.json +11 -6
|
@@ -0,0 +1,94 @@
|
|
|
1
|
+
# Cleanup Hook Boundary
|
|
2
|
+
|
|
3
|
+
This boundary maps pharo-launcher-mcp status, timeout, stop, and cleanup
|
|
4
|
+
surfaces for caller-managed isolated live checks. It documents the launcher
|
|
5
|
+
server's contract only; callers own higher-level project policy, approval,
|
|
6
|
+
artifact retention, and cleanup orchestration.
|
|
7
|
+
|
|
8
|
+
## Read-Only Inspection
|
|
9
|
+
|
|
10
|
+
These checks are safe for planning and static verification:
|
|
11
|
+
|
|
12
|
+
- `npm test`, `npm run typecheck`, and `npm run build`
|
|
13
|
+
- `git status --short --branch`
|
|
14
|
+
- source review of command schemas, parser behavior, result envelopes, and
|
|
15
|
+
timeout handling
|
|
16
|
+
- `pharo_launcher_health`, because it reports resolved paths without invoking
|
|
17
|
+
Pharo Launcher
|
|
18
|
+
- `pharo_launcher_config`, because it reports resolved configuration without
|
|
19
|
+
invoking Pharo Launcher
|
|
20
|
+
|
|
21
|
+
These checks inspect live host state or invoke Pharo Launcher. Run them only
|
|
22
|
+
when the caller has chosen to cross that boundary:
|
|
23
|
+
|
|
24
|
+
- `pharo_launcher_version`
|
|
25
|
+
- `pharo_launcher_validate_installation`
|
|
26
|
+
- `pharo_launcher_image_list`
|
|
27
|
+
- `pharo_launcher_image_info`
|
|
28
|
+
- `pharo_launcher_process_list`
|
|
29
|
+
|
|
30
|
+
They are non-mutating, but they still cross the live host boundary.
|
|
31
|
+
|
|
32
|
+
## Status Signals
|
|
33
|
+
|
|
34
|
+
The existing launcher result envelope carries status data for callers:
|
|
35
|
+
|
|
36
|
+
- `ok`
|
|
37
|
+
- `parser.status`
|
|
38
|
+
- normalized `data` when parsing is supported
|
|
39
|
+
- raw `stdout` and `stderr`
|
|
40
|
+
- command `durationMs`
|
|
41
|
+
- command `exitCode`
|
|
42
|
+
- command `timedOut`
|
|
43
|
+
- optional `timeoutReason`
|
|
44
|
+
|
|
45
|
+
For cleanup decisions, callers must prefer normalized image and process data.
|
|
46
|
+
Raw output is diagnostic evidence, not ownership proof.
|
|
47
|
+
|
|
48
|
+
## Stop And Cleanup Hooks
|
|
49
|
+
|
|
50
|
+
The mutation hooks that can participate in cleanup are:
|
|
51
|
+
|
|
52
|
+
- `pharo_launcher_process_kill` with `confirm: true`
|
|
53
|
+
- `pharo_launcher_image_delete` with `confirm: true`
|
|
54
|
+
- `pharo_launcher_image_recreate` with `confirm: true`, only for explicitly
|
|
55
|
+
disposable images
|
|
56
|
+
- profile-root cleanup by the caller after logs and diagnostics are retained
|
|
57
|
+
|
|
58
|
+
The caller must pass either a recorded pid or an owned image name. Ambiguous
|
|
59
|
+
cleanup input is not allowed. It must never use these hooks against the user's
|
|
60
|
+
source image, default profile, unrelated images, unrelated VMs, or a process
|
|
61
|
+
that cannot be tied to the smoke run.
|
|
62
|
+
|
|
63
|
+
## Timeout Boundary
|
|
64
|
+
|
|
65
|
+
Every launcher call must have a bounded timeout supplied by the caller or by
|
|
66
|
+
the server default. A timeout means the caller records the phase as failed,
|
|
67
|
+
retains command metadata, and continues with owned cleanup. A timeout does not
|
|
68
|
+
authorize broader host cleanup.
|
|
69
|
+
|
|
70
|
+
## Profile And Artifact Boundary
|
|
71
|
+
|
|
72
|
+
A future isolated live check must use a disposable profile rooted by
|
|
73
|
+
`PHARO_LAUNCHER_MCP_STATE_ROOT` or the explicit profile path variables:
|
|
74
|
+
|
|
75
|
+
- `PHARO_LAUNCHER_MCP_LAUNCHER_IMAGE`
|
|
76
|
+
- `PHARO_LAUNCHER_MCP_IMAGES_DIR`
|
|
77
|
+
- `PHARO_LAUNCHER_MCP_VMS_DIR`
|
|
78
|
+
- `PHARO_LAUNCHER_MCP_TEMPLATE_SOURCES_DIR`
|
|
79
|
+
- `PHARO_LAUNCHER_MCP_INIT_SCRIPTS_DIR`
|
|
80
|
+
- `PHARO_LAUNCHER_MCP_LOGS_DIR`
|
|
81
|
+
|
|
82
|
+
Retain the launcher logs, command envelopes, image names, image paths, process
|
|
83
|
+
pids, and timeout reasons before deleting disposable directories.
|
|
84
|
+
|
|
85
|
+
## Follow-Up Policy
|
|
86
|
+
|
|
87
|
+
No launcher-side blocking hook gap is currently identified for caller-managed
|
|
88
|
+
isolated live checks. pharo-launcher-mcp exposes the needed status, timeout,
|
|
89
|
+
image delete, and process kill primitives. Callers still own higher-level
|
|
90
|
+
ownership, approval, artifact retention, and idempotent cleanup policy.
|
|
91
|
+
|
|
92
|
+
If a future caller needs one atomic cleanup/report command instead of composing
|
|
93
|
+
the existing primitives, create a pharo-launcher-mcp follow-up work item. Do
|
|
94
|
+
not bypass the safety gate with raw host commands.
|
package/docs/development.md
CHANGED
|
@@ -1,9 +1,9 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Development
|
|
2
2
|
|
|
3
|
-
This document
|
|
4
|
-
focused on installation
|
|
3
|
+
This document is for maintainers changing pharo-launcher-mcp. The README stays
|
|
4
|
+
focused on installation and first use; user-facing detail lives under `docs/`.
|
|
5
5
|
|
|
6
|
-
## Source
|
|
6
|
+
## Source layout
|
|
7
7
|
|
|
8
8
|
- `src/server.ts`: MCP server surface and tool dispatch.
|
|
9
9
|
- `src/commandCatalog.ts`: Pharo Launcher command definitions and input checks.
|
|
@@ -18,12 +18,11 @@ focused on installation, configuration, and tool usage.
|
|
|
18
18
|
- `bin/pharo-launcher.sh`: POSIX wrapper.
|
|
19
19
|
- `scripts/*.ps1`: Windows helper scripts for local live checks.
|
|
20
20
|
|
|
21
|
-
## Local
|
|
21
|
+
## Local setup
|
|
22
22
|
|
|
23
23
|
```sh
|
|
24
24
|
npm install
|
|
25
|
-
npm run
|
|
26
|
-
npm test
|
|
25
|
+
npm run check
|
|
27
26
|
```
|
|
28
27
|
|
|
29
28
|
Useful scripts:
|
|
@@ -35,33 +34,45 @@ npm test
|
|
|
35
34
|
npm run test:integration
|
|
36
35
|
```
|
|
37
36
|
|
|
38
|
-
`npm
|
|
37
|
+
`npm run check` runs type checking, build, and unit tests. `npm test` runs unit
|
|
38
|
+
coverage only. It does not invoke a local Pharo Launcher.
|
|
39
39
|
|
|
40
|
-
## Platform
|
|
40
|
+
## Platform contract
|
|
41
41
|
|
|
42
42
|
The production code handles Windows, macOS, and Linux explicitly:
|
|
43
43
|
|
|
44
44
|
- Windows defaults to `%LOCALAPPDATA%\Pharo Launcher`,
|
|
45
45
|
`PharoConsole.exe`, and `pharo-launcher.cmd`.
|
|
46
|
-
- macOS
|
|
47
|
-
|
|
46
|
+
- macOS discovery checks `$HOME/Applications/PharoLauncher.app` and
|
|
47
|
+
`/Applications/PharoLauncher.app` before falling back to
|
|
48
|
+
`$HOME/Library/Application Support/Pharo Launcher`. App-bundle installs use
|
|
49
|
+
`Contents/MacOS/Pharo` and `Contents/Resources/PharoLauncher.image`.
|
|
48
50
|
- Linux defaults to `$HOME/.local/share/Pharo Launcher`, `pharo-vm/pharo`,
|
|
49
51
|
and `pharo-launcher.sh`.
|
|
50
52
|
|
|
51
53
|
`src/crossPlatform.test.ts` covers configuration defaults, bundled wrapper
|
|
52
54
|
selection, and native process backend selection for all three platforms.
|
|
55
|
+
`src/config.test.ts` covers macOS app-bundle discovery, fallback, and explicit
|
|
56
|
+
environment override precedence.
|
|
53
57
|
|
|
54
|
-
|
|
58
|
+
No-profile mode means no pharo-launcher-mcp profile is active and no
|
|
59
|
+
pharo-launcher-mcp home/cache is created. The resolved Pharo Launcher
|
|
60
|
+
installation and its normal state scope are used directly. Profile mode is
|
|
61
|
+
entered only when `PHARO_LAUNCHER_MCP_PROFILE`,
|
|
62
|
+
`PHARO_LAUNCHER_MCP_STATE_ROOT`, or one of the explicit profile directory
|
|
63
|
+
variables is present.
|
|
55
64
|
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
65
|
+
## Process backend
|
|
66
|
+
|
|
67
|
+
Pharo Launcher process commands can vary by host. pharo-launcher-mcp uses a
|
|
68
|
+
native process backend for `pharo_launcher_process_list` and
|
|
69
|
+
`pharo_launcher_process_kill` when needed:
|
|
59
70
|
|
|
60
71
|
- Windows uses a PowerShell/CIM query.
|
|
61
72
|
- macOS and Linux use `ps -axo pid=,args=`.
|
|
62
73
|
- Unsupported host platforms return an explicit unsupported-backend error.
|
|
63
74
|
|
|
64
|
-
## Parsing
|
|
75
|
+
## Parsing boundary
|
|
65
76
|
|
|
66
77
|
`src/parser.ts` is the only layer that translates Pharo Launcher output into
|
|
67
78
|
pharo-launcher-mcp models.
|
|
@@ -86,7 +97,14 @@ LauncherProcess
|
|
|
86
97
|
LauncherCommandResult
|
|
87
98
|
```
|
|
88
99
|
|
|
89
|
-
|
|
100
|
+
Inventory output adds normalized identity metadata on top of parsed launcher
|
|
101
|
+
models. Template identities normalize Pharo and Moose template names to the
|
|
102
|
+
underlying Pharo version when possible, infer architecture from template names
|
|
103
|
+
or URLs, and attach source-file digest/mtime for installed `.ston` template
|
|
104
|
+
files. Image identities mirror the launcher metadata returned by image
|
|
105
|
+
list/info commands.
|
|
106
|
+
|
|
107
|
+
## Integration tests
|
|
90
108
|
|
|
91
109
|
Run the live integration suite explicitly:
|
|
92
110
|
|
|
@@ -119,10 +137,10 @@ External-source image creation variants such as build, pull request,
|
|
|
119
137
|
repository, SHA, and VM mutation commands should use explicit fixtures because
|
|
120
138
|
they require network inputs or can alter VM installations.
|
|
121
139
|
|
|
122
|
-
## Windows
|
|
140
|
+
## Windows live helpers
|
|
123
141
|
|
|
124
142
|
The helper scripts under `scripts/*.ps1` are Windows PowerShell conveniences for
|
|
125
|
-
|
|
143
|
+
a local Windows development environment:
|
|
126
144
|
|
|
127
145
|
```powershell
|
|
128
146
|
.\scripts\verify-environment.ps1
|
|
@@ -134,10 +152,10 @@ The live smoke test uses a dedicated profile root and copies the Pharo Launcher
|
|
|
134
152
|
control image there before making live calls. It runs harmless checks by
|
|
135
153
|
default: health, `--version`, and installation validation.
|
|
136
154
|
|
|
137
|
-
|
|
155
|
+
When `-StateRoot` is not supplied, the helper uses:
|
|
138
156
|
|
|
139
157
|
```text
|
|
140
|
-
|
|
158
|
+
<repo-parent>\.pharo-launcher-mcp\profiles\live-test
|
|
141
159
|
```
|
|
142
160
|
|
|
143
161
|
Refresh the copied launcher control image:
|
|
@@ -149,7 +167,13 @@ Refresh the copied launcher control image:
|
|
|
149
167
|
These helpers are not a substitute for cross-platform verification on macOS and
|
|
150
168
|
Linux.
|
|
151
169
|
|
|
152
|
-
##
|
|
170
|
+
## Cleanup hook boundary
|
|
171
|
+
|
|
172
|
+
Use `docs/cleanup-hook-boundary.md` when mapping launcher status, stop,
|
|
173
|
+
timeout, and cleanup hooks for isolated live checks. That boundary
|
|
174
|
+
distinguishes read-only planning checks from host inspection and mutation.
|
|
175
|
+
|
|
176
|
+
## Local probes
|
|
153
177
|
|
|
154
178
|
Probe the local Pharo Launcher image list without starting MCP stdio:
|
|
155
179
|
|
|
@@ -164,3 +188,21 @@ Start the MCP server over stdio from a local build:
|
|
|
164
188
|
```powershell
|
|
165
189
|
node .\dist\index.js
|
|
166
190
|
```
|
|
191
|
+
|
|
192
|
+
## Documentation updates
|
|
193
|
+
|
|
194
|
+
Keep docs close to the behavior they describe:
|
|
195
|
+
|
|
196
|
+
- Put the fastest install and health path in `README.md`.
|
|
197
|
+
- Put profile details in `docs/user/profile-mode.md`.
|
|
198
|
+
- Put tool arguments and result shape in `docs/reference/tools.md`.
|
|
199
|
+
- Put live host failure modes in `docs/troubleshooting.md`.
|
|
200
|
+
- Keep examples generic. Do not use local machine paths, project names, issue
|
|
201
|
+
numbers, or incident history as examples.
|
|
202
|
+
|
|
203
|
+
Before committing docs changes, run:
|
|
204
|
+
|
|
205
|
+
```sh
|
|
206
|
+
npm run check
|
|
207
|
+
npm pack --dry-run
|
|
208
|
+
```
|
|
@@ -0,0 +1,179 @@
|
|
|
1
|
+
# Tool Reference
|
|
2
|
+
|
|
3
|
+
pharo-launcher-mcp exposes MCP tools over stdio. Most tools call Pharo Launcher
|
|
4
|
+
and return a normalized launcher result envelope. Health and configuration tools
|
|
5
|
+
only inspect local paths.
|
|
6
|
+
|
|
7
|
+
## Health And Configuration
|
|
8
|
+
|
|
9
|
+
| Tool | Live Launcher invocation | Purpose |
|
|
10
|
+
| --- | --- | --- |
|
|
11
|
+
| `pharo_launcher_health` | No | Reports service version, resolved paths, wrapper source, and existence checks. |
|
|
12
|
+
| `pharo_launcher_config` | No | Reports resolved installation, profile, wrapper, and configuration paths. |
|
|
13
|
+
| `pharo_launcher_version` | Yes | Runs `--version`. |
|
|
14
|
+
| `pharo_launcher_validate_installation` | Yes | Checks resolved paths and runs `--version`. |
|
|
15
|
+
| `pharo_launcher_inventory` | Yes | Reports profile roots, templates, image identities, declared image handles, probes, and diagnostics. |
|
|
16
|
+
|
|
17
|
+
`pharo_launcher_inventory` accepts optional `declaredImages` supplied by a
|
|
18
|
+
scoped caller:
|
|
19
|
+
|
|
20
|
+
```json
|
|
21
|
+
{
|
|
22
|
+
"declaredImages": [
|
|
23
|
+
{
|
|
24
|
+
"imageId": "image:sample-130",
|
|
25
|
+
"imageName": "sample-130",
|
|
26
|
+
"status": "active"
|
|
27
|
+
}
|
|
28
|
+
]
|
|
29
|
+
}
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
## Image Tools
|
|
33
|
+
|
|
34
|
+
| Tool | Arguments |
|
|
35
|
+
| --- | --- |
|
|
36
|
+
| `pharo_launcher_image_list` | `nameFilter`, table options |
|
|
37
|
+
| `pharo_launcher_image_info` | `imageName`, table options |
|
|
38
|
+
| `pharo_launcher_image_create` | `templateName`, `newImageName`, `templateCategory`, `dev`, `noLaunch` |
|
|
39
|
+
| `pharo_launcher_image_copy` | `imageName`, `newImageName` |
|
|
40
|
+
| `pharo_launcher_image_copy_between_profiles` | `sourceProfile`, `destinationProfile`, `sourceImageName`, `destinationImageName` |
|
|
41
|
+
| `pharo_launcher_image_launch` | `imageName`, `script`, `detached`, `displayMode` |
|
|
42
|
+
| `pharo_launcher_image_package` | `imageName`, `location`, `zip`, `vm` |
|
|
43
|
+
| `pharo_launcher_image_bisect` | `pharoVersion` |
|
|
44
|
+
| `pharo_launcher_image_create_from_build` | `buildNumber`, `pharoVersion`, `newImageName` |
|
|
45
|
+
| `pharo_launcher_image_create_from_pull_request` | `pullRequest`, `newImageName`, `templateName`, `templateCategory` |
|
|
46
|
+
| `pharo_launcher_image_create_from_repo` | `repository`, `newImageName`, `templateName`, `templateCategory`, `subfolder`, `baseline`, `group` |
|
|
47
|
+
| `pharo_launcher_image_create_from_sha` | `sha`, `pharoVersion`, `newImageName` |
|
|
48
|
+
| `pharo_launcher_image_delete` | `imageName`, `force`, `confirm: true` |
|
|
49
|
+
| `pharo_launcher_image_recreate` | `imageName`, `confirm: true` |
|
|
50
|
+
|
|
51
|
+
`pharo_launcher_image_create` and `pharo_launcher_image_copy` verify the target
|
|
52
|
+
image after Launcher returns. A successful Launcher exit is not enough: the MCP
|
|
53
|
+
result is successful only when the target image can be listed and inspected.
|
|
54
|
+
|
|
55
|
+
`pharo_launcher_image_launch` supports:
|
|
56
|
+
|
|
57
|
+
- `displayMode: "headless"` or `"interactive"`
|
|
58
|
+
- `detached: true` for detached launches with log paths in the result
|
|
59
|
+
- `script` for a launch script passed to Launcher, or evaluated by the profile
|
|
60
|
+
VM launch path
|
|
61
|
+
|
|
62
|
+
In profile mode, image launch resolves the image and VM inside the active
|
|
63
|
+
profile roots instead of using Launcher defaults.
|
|
64
|
+
|
|
65
|
+
## Template Tools
|
|
66
|
+
|
|
67
|
+
| Tool | Arguments |
|
|
68
|
+
| --- | --- |
|
|
69
|
+
| `pharo_launcher_template_category_list` | table options |
|
|
70
|
+
| `pharo_launcher_template_list` | `templateCategory`, table options |
|
|
71
|
+
| `pharo_launcher_template_info` | `templateName`, `templateCategory` |
|
|
72
|
+
| `pharo_launcher_template_update` | none |
|
|
73
|
+
|
|
74
|
+
Table options are:
|
|
75
|
+
|
|
76
|
+
```json
|
|
77
|
+
{
|
|
78
|
+
"format": "ston",
|
|
79
|
+
"brief": true,
|
|
80
|
+
"rowMode": true,
|
|
81
|
+
"delimiter": "|"
|
|
82
|
+
}
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
`format` can be `ston` or `text`. The default is `ston` when a tool supports
|
|
86
|
+
table output.
|
|
87
|
+
|
|
88
|
+
In profile mode, `pharo_launcher_template_update` also verifies that the active
|
|
89
|
+
profile source list is usable and probes `template list`.
|
|
90
|
+
|
|
91
|
+
## VM Tools
|
|
92
|
+
|
|
93
|
+
| Tool | Arguments |
|
|
94
|
+
| --- | --- |
|
|
95
|
+
| `pharo_launcher_vm_list` | `vmId`, table options |
|
|
96
|
+
| `pharo_launcher_vm_info` | `vmId` |
|
|
97
|
+
| `pharo_launcher_vm_update` | `vmId` |
|
|
98
|
+
| `pharo_launcher_vm_delete` | `vmId`, `confirm: true` |
|
|
99
|
+
|
|
100
|
+
VM update can download or install VM files. Use profile mode when automation
|
|
101
|
+
needs VM state isolated from a user's normal Launcher installation.
|
|
102
|
+
|
|
103
|
+
## Process Tools
|
|
104
|
+
|
|
105
|
+
| Tool | Arguments |
|
|
106
|
+
| --- | --- |
|
|
107
|
+
| `pharo_launcher_process_list` | none |
|
|
108
|
+
| `pharo_launcher_process_kill` | exactly one of `pid` or `imageName`, plus `confirm: true` |
|
|
109
|
+
|
|
110
|
+
On Windows, process tools use PowerShell/CIM. On macOS and Linux, they use
|
|
111
|
+
`ps -axo pid=,args=`. Unsupported platforms return an explicit unsupported
|
|
112
|
+
backend error.
|
|
113
|
+
|
|
114
|
+
Prefer PID-based cleanup when a prior detached launch returned a PID. Image-name
|
|
115
|
+
cleanup can match more than one process if multiple command lines contain the
|
|
116
|
+
same image name.
|
|
117
|
+
|
|
118
|
+
## Raw Command
|
|
119
|
+
|
|
120
|
+
`pharo_launcher_raw_command` is the escape hatch for Launcher CLI arguments not
|
|
121
|
+
covered by a dedicated MCP tool:
|
|
122
|
+
|
|
123
|
+
```json
|
|
124
|
+
{
|
|
125
|
+
"args": ["image", "list", "--ston"],
|
|
126
|
+
"confirm": true
|
|
127
|
+
}
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
It always requires `confirm: true`.
|
|
131
|
+
|
|
132
|
+
## Result Envelope
|
|
133
|
+
|
|
134
|
+
Launcher tools return JSON shaped like this:
|
|
135
|
+
|
|
136
|
+
```ts
|
|
137
|
+
{
|
|
138
|
+
ok: boolean;
|
|
139
|
+
data?: unknown;
|
|
140
|
+
diagnostic?: string;
|
|
141
|
+
action?: string;
|
|
142
|
+
parser: {
|
|
143
|
+
status: "parsed" | "unsupported" | "failed" | "skipped";
|
|
144
|
+
format: "ston" | "text";
|
|
145
|
+
message?: string;
|
|
146
|
+
};
|
|
147
|
+
raw: {
|
|
148
|
+
stdout: string;
|
|
149
|
+
stderr: string;
|
|
150
|
+
format: "ston" | "text";
|
|
151
|
+
};
|
|
152
|
+
command: {
|
|
153
|
+
args: string[];
|
|
154
|
+
durationMs: number;
|
|
155
|
+
exitCode: number | null;
|
|
156
|
+
timedOut: boolean;
|
|
157
|
+
timeoutReason?: string;
|
|
158
|
+
};
|
|
159
|
+
}
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
Use `ok` and normalized `data` for program flow. Treat `raw.stdout` and
|
|
163
|
+
`raw.stderr` as diagnostics.
|
|
164
|
+
|
|
165
|
+
## Confirmation Gates
|
|
166
|
+
|
|
167
|
+
These tools require `confirm: true`:
|
|
168
|
+
|
|
169
|
+
```text
|
|
170
|
+
pharo_launcher_image_delete
|
|
171
|
+
pharo_launcher_image_recreate
|
|
172
|
+
pharo_launcher_vm_delete
|
|
173
|
+
pharo_launcher_process_kill
|
|
174
|
+
pharo_launcher_raw_command
|
|
175
|
+
```
|
|
176
|
+
|
|
177
|
+
The confirmation flag only confirms that the caller meant to cross that tool's
|
|
178
|
+
mutation boundary. It does not prove the image, VM, profile, or process is
|
|
179
|
+
caller-owned.
|
|
@@ -0,0 +1,135 @@
|
|
|
1
|
+
# Troubleshooting
|
|
2
|
+
|
|
3
|
+
Start with `pharo_launcher_health` or the local CLI health check:
|
|
4
|
+
|
|
5
|
+
```sh
|
|
6
|
+
npx @evref-bl/pharo-launcher-mcp --health
|
|
7
|
+
```
|
|
8
|
+
|
|
9
|
+
Health checks do not invoke Pharo Launcher. They show the resolved installation,
|
|
10
|
+
control image, VM path, wrapper path, profile paths, and whether those paths
|
|
11
|
+
exist.
|
|
12
|
+
|
|
13
|
+
## Launcher Paths Are Wrong
|
|
14
|
+
|
|
15
|
+
Set the installation paths explicitly:
|
|
16
|
+
|
|
17
|
+
```sh
|
|
18
|
+
PHARO_LAUNCHER_DIR="/path/to/Pharo Launcher"
|
|
19
|
+
PHARO_LAUNCHER_VM="/path/to/pharo"
|
|
20
|
+
PHARO_LAUNCHER_IMAGE="/path/to/PharoLauncher.image"
|
|
21
|
+
PHARO_LAUNCHER_SCRIPT="/path/to/pharo-launcher.sh"
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
Then run:
|
|
25
|
+
|
|
26
|
+
```sh
|
|
27
|
+
npx @evref-bl/pharo-launcher-mcp --health
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
On macOS, the server checks user and system `PharoLauncher.app` locations before
|
|
31
|
+
falling back to the Application Support layout. The health report includes the
|
|
32
|
+
selected discovery source and all attempted candidates.
|
|
33
|
+
|
|
34
|
+
## Wrapper Is Missing
|
|
35
|
+
|
|
36
|
+
`PHARO_LAUNCHER_SCRIPT` is optional. If it is unset, the server tries the
|
|
37
|
+
bundled wrapper for the host platform. If that wrapper cannot be resolved, the
|
|
38
|
+
server invokes the VM directly with the Launcher control image.
|
|
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.
|
|
43
|
+
|
|
44
|
+
## `validate_installation` Fails
|
|
45
|
+
|
|
46
|
+
`pharo_launcher_validate_installation` runs `--version`. If it fails:
|
|
47
|
+
|
|
48
|
+
1. Run `pharo_launcher_config` and confirm the VM and control image paths.
|
|
49
|
+
2. Run `pharo_launcher_health` and check `launcherScript.exists`.
|
|
50
|
+
3. If using a profile, confirm the installation control image exists. The
|
|
51
|
+
profile control image is copied from that source before live commands.
|
|
52
|
+
4. Try `node ./dist/index.js --version-check` from a local build to separate MCP
|
|
53
|
+
client setup from Launcher startup.
|
|
54
|
+
|
|
55
|
+
## Profile Configuration Is Refused
|
|
56
|
+
|
|
57
|
+
When `PHARO_LAUNCHER_MCP_STATE_ROOT` is set, the profile launcher image and
|
|
58
|
+
generated Launcher configuration must be inside that state root.
|
|
59
|
+
|
|
60
|
+
Use a state-root layout:
|
|
61
|
+
|
|
62
|
+
```text
|
|
63
|
+
<state-root>/launcher/PharoLauncher.image
|
|
64
|
+
<state-root>/launcher/pharo-launcher-cli-config.ston
|
|
65
|
+
<state-root>/images
|
|
66
|
+
<state-root>/vms
|
|
67
|
+
<state-root>/templates
|
|
68
|
+
<state-root>/init-scripts
|
|
69
|
+
<state-root>/logs
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
Or provide a complete explicit profile without relying on `stateRoot`. See
|
|
73
|
+
[Profile mode](user/profile-mode.md).
|
|
74
|
+
|
|
75
|
+
## Template List Fails In Profile Mode
|
|
76
|
+
|
|
77
|
+
Run:
|
|
78
|
+
|
|
79
|
+
```text
|
|
80
|
+
pharo_launcher_template_update
|
|
81
|
+
pharo_launcher_inventory
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
`template_update` seeds the active profile source list when Launcher leaves it
|
|
85
|
+
missing or empty, then probes `template list`. Inventory diagnostics report
|
|
86
|
+
missing profile directories, missing configuration files, and failed probes.
|
|
87
|
+
|
|
88
|
+
## Image Create Or Copy Reports An Error After Launcher Succeeds
|
|
89
|
+
|
|
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.
|
|
92
|
+
|
|
93
|
+
Check:
|
|
94
|
+
|
|
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
|
+
|
|
104
|
+
## Process List Or Kill Does Not See A Process
|
|
105
|
+
|
|
106
|
+
Process tools use native host process queries:
|
|
107
|
+
|
|
108
|
+
- Windows: PowerShell/CIM
|
|
109
|
+
- macOS and Linux: `ps -axo pid=,args=`
|
|
110
|
+
|
|
111
|
+
The process must have a Pharo or Squeak command line that includes a `.image`
|
|
112
|
+
path. For cleanup, prefer a PID captured from the detached launch result. If
|
|
113
|
+
using `imageName`, confirm that no unrelated process command line contains the
|
|
114
|
+
same text.
|
|
115
|
+
|
|
116
|
+
## Commands Time Out
|
|
117
|
+
|
|
118
|
+
Every Launcher command is bounded by a timeout. Timeout results include:
|
|
119
|
+
|
|
120
|
+
- `command.timedOut: true`
|
|
121
|
+
- `command.timeoutReason`
|
|
122
|
+
- command args
|
|
123
|
+
- raw stdout/stderr captured before the timeout
|
|
124
|
+
|
|
125
|
+
A timeout does not authorize broader host cleanup. Cleanup should use only
|
|
126
|
+
recorded image names, profile roots, and PIDs that the caller owns.
|
|
127
|
+
|
|
128
|
+
## Profile `create_from_build` Is Refused
|
|
129
|
+
|
|
130
|
+
Profile-scoped `pharo_launcher_image_create_from_build` is refused before
|
|
131
|
+
Launcher starts. That Launcher path can automatically launch the image and may
|
|
132
|
+
download or use VMs outside `PHARO_LAUNCHER_MCP_VMS_DIR`.
|
|
133
|
+
|
|
134
|
+
Use a non-`fromBuild` creation path with explicit launch control, or run the
|
|
135
|
+
operation outside profile mode when using the normal Launcher state is intended.
|