@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.
- package/README.md +229 -199
- 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 +23 -6
- 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 +75 -6
- package/dist/config.js.map +1 -1
- package/dist/crossProfileCopy.d.ts +88 -0
- package/dist/crossProfileCopy.d.ts.map +1 -0
- package/dist/crossProfileCopy.js +511 -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 +803 -3
- package/dist/discovery.js.map +1 -1
- package/dist/imageMetadata.d.ts +1 -0
- package/dist/imageMetadata.d.ts.map +1 -1
- package/dist/imageMetadata.js +35 -2
- package/dist/imageMetadata.js.map +1 -1
- package/dist/launcherCli.d.ts +2 -0
- package/dist/launcherCli.d.ts.map +1 -1
- package/dist/launcherCli.js +589 -62
- package/dist/launcherCli.js.map +1 -1
- package/dist/models.d.ts +3 -1
- package/dist/models.d.ts.map +1 -1
- package/dist/parser.d.ts.map +1 -1
- package/dist/parser.js +48 -13
- package/dist/parser.js.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/processTools.d.ts.map +1 -1
- package/dist/processTools.js +13 -7
- package/dist/processTools.js.map +1 -1
- package/dist/resultNormalizer.d.ts +5 -1
- package/dist/resultNormalizer.d.ts.map +1 -1
- package/dist/resultNormalizer.js +79 -6
- package/dist/resultNormalizer.js.map +1 -1
- package/dist/server.d.ts +3 -0
- package/dist/server.d.ts.map +1 -1
- package/dist/server.js +475 -83
- package/dist/server.js.map +1 -1
- package/dist/textTokens.d.ts +10 -0
- package/dist/textTokens.d.ts.map +1 -0
- package/dist/textTokens.js +68 -0
- package/dist/textTokens.js.map +1 -0
- package/docs/README.md +26 -0
- package/docs/cleanup-hook-boundary.md +94 -0
- package/docs/development.md +59 -23
- 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 +183 -0
- package/package.json +59 -52
|
@@ -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.
|
|
@@ -0,0 +1,172 @@
|
|
|
1
|
+
# Getting Started
|
|
2
|
+
|
|
3
|
+
This guide gets pharo-launcher-mcp running as a stdio MCP server and shows the
|
|
4
|
+
first checks to run before mutating any Launcher state.
|
|
5
|
+
|
|
6
|
+
## Requirements
|
|
7
|
+
|
|
8
|
+
- Node.js 22.12.0 or newer
|
|
9
|
+
- `npm` and `npx`
|
|
10
|
+
- A local Pharo Launcher installation
|
|
11
|
+
- An MCP client that can start a stdio server
|
|
12
|
+
|
|
13
|
+
## Install
|
|
14
|
+
|
|
15
|
+
Install the package in a project:
|
|
16
|
+
|
|
17
|
+
```sh
|
|
18
|
+
npm install @evref-bl/pharo-launcher-mcp
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
Or run it directly with `npx`:
|
|
22
|
+
|
|
23
|
+
```sh
|
|
24
|
+
npx @evref-bl/pharo-launcher-mcp
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
The server prints MCP JSON-RPC messages on stdio. For a human-readable local
|
|
28
|
+
check, run the health command instead:
|
|
29
|
+
|
|
30
|
+
```sh
|
|
31
|
+
npx @evref-bl/pharo-launcher-mcp --health
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
`--health` reports resolved paths and wrapper availability. It does not invoke
|
|
35
|
+
Pharo Launcher.
|
|
36
|
+
|
|
37
|
+
## Discovery
|
|
38
|
+
|
|
39
|
+
pharo-launcher-mcp resolves the Launcher installation from environment
|
|
40
|
+
variables first. If they are not set, it uses host defaults.
|
|
41
|
+
|
|
42
|
+
| Host OS | Launcher directory | VM path | Wrapper |
|
|
43
|
+
| --- | --- | --- | --- |
|
|
44
|
+
| Windows | `%LOCALAPPDATA%\Pharo Launcher` | `<launcher-dir>\PharoConsole.exe` | `pharo-launcher.cmd` |
|
|
45
|
+
| macOS app bundle | `$HOME/Applications/PharoLauncher.app` or `/Applications/PharoLauncher.app` | `<app>/Contents/MacOS/Pharo` | `pharo-launcher.sh` |
|
|
46
|
+
| macOS data directory | `$HOME/Library/Application Support/Pharo Launcher` | `<launcher-dir>/pharo-vm/Pharo.app/Contents/MacOS/Pharo` | `pharo-launcher.sh` |
|
|
47
|
+
| Linux | `$HOME/.local/share/Pharo Launcher` | `<launcher-dir>/pharo-vm/pharo` | `pharo-launcher.sh` |
|
|
48
|
+
|
|
49
|
+
For macOS app bundles, the control image is
|
|
50
|
+
`<app>/Contents/Resources/PharoLauncher.image`.
|
|
51
|
+
|
|
52
|
+
Override the installation when needed:
|
|
53
|
+
|
|
54
|
+
```sh
|
|
55
|
+
PHARO_LAUNCHER_DIR="/path/to/Pharo Launcher"
|
|
56
|
+
PHARO_LAUNCHER_VM="/path/to/pharo"
|
|
57
|
+
PHARO_LAUNCHER_IMAGE="/path/to/PharoLauncher.image"
|
|
58
|
+
PHARO_LAUNCHER_SCRIPT="/path/to/pharo-launcher.sh"
|
|
59
|
+
npx @evref-bl/pharo-launcher-mcp --health
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
PowerShell:
|
|
63
|
+
|
|
64
|
+
```powershell
|
|
65
|
+
$env:PHARO_LAUNCHER_DIR="C:\Path\To\Pharo Launcher"
|
|
66
|
+
$env:PHARO_LAUNCHER_VM="$env:PHARO_LAUNCHER_DIR\PharoConsole.exe"
|
|
67
|
+
$env:PHARO_LAUNCHER_IMAGE="$env:PHARO_LAUNCHER_DIR\PharoLauncher.image"
|
|
68
|
+
$env:PHARO_LAUNCHER_SCRIPT="C:\Path\To\pharo-launcher.cmd"
|
|
69
|
+
npx @evref-bl/pharo-launcher-mcp --health
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
`PHARO_LAUNCHER_SCRIPT` is optional. If it is not set, the server tries its
|
|
73
|
+
bundled wrapper for the host platform. If no wrapper is available, it invokes
|
|
74
|
+
the VM directly with:
|
|
75
|
+
|
|
76
|
+
```text
|
|
77
|
+
--headless <PharoLauncher.image> --no-default-preferences clap launcher ...
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
## MCP Client Setup
|
|
81
|
+
|
|
82
|
+
A generic MCP client entry looks like this:
|
|
83
|
+
|
|
84
|
+
```json
|
|
85
|
+
{
|
|
86
|
+
"mcpServers": {
|
|
87
|
+
"pharo-launcher": {
|
|
88
|
+
"command": "npx",
|
|
89
|
+
"args": ["-y", "@evref-bl/pharo-launcher-mcp"]
|
|
90
|
+
}
|
|
91
|
+
}
|
|
92
|
+
}
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
If the package is installed in a project, point the client at the package
|
|
96
|
+
executable from that project environment:
|
|
97
|
+
|
|
98
|
+
```json
|
|
99
|
+
{
|
|
100
|
+
"mcpServers": {
|
|
101
|
+
"pharo-launcher": {
|
|
102
|
+
"command": "pharo-launcher-mcp"
|
|
103
|
+
}
|
|
104
|
+
}
|
|
105
|
+
}
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
For a profile-backed server, add the profile environment variables to the MCP
|
|
109
|
+
client entry. See [Profile mode](profile-mode.md).
|
|
110
|
+
|
|
111
|
+
## First Tools
|
|
112
|
+
|
|
113
|
+
Run read-only checks first:
|
|
114
|
+
|
|
115
|
+
```text
|
|
116
|
+
pharo_launcher_health
|
|
117
|
+
pharo_launcher_config
|
|
118
|
+
pharo_launcher_validate_installation
|
|
119
|
+
pharo_launcher_inventory
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
Use the output this way:
|
|
123
|
+
|
|
124
|
+
- `pharo_launcher_health` confirms whether the resolved directory, VM, control
|
|
125
|
+
image, and wrapper exist. It does not invoke Pharo Launcher.
|
|
126
|
+
- `pharo_launcher_config` shows the same resolved configuration in a direct
|
|
127
|
+
report.
|
|
128
|
+
- `pharo_launcher_validate_installation` runs `--version` and verifies that the
|
|
129
|
+
launcher command can start.
|
|
130
|
+
- `pharo_launcher_inventory` gathers templates, images, profile roots, and
|
|
131
|
+
declared image handles for lifecycle planning.
|
|
132
|
+
|
|
133
|
+
After validation, list templates:
|
|
134
|
+
|
|
135
|
+
```text
|
|
136
|
+
pharo_launcher_template_update
|
|
137
|
+
pharo_launcher_template_list
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
Then create an image with an explicit name:
|
|
141
|
+
|
|
142
|
+
```json
|
|
143
|
+
{
|
|
144
|
+
"tool": "pharo_launcher_image_create",
|
|
145
|
+
"arguments": {
|
|
146
|
+
"templateName": "Pharo 13.0 - 64bit",
|
|
147
|
+
"newImageName": "sample-130",
|
|
148
|
+
"noLaunch": true
|
|
149
|
+
}
|
|
150
|
+
}
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
The create result is only successful when the new image can be listed and
|
|
154
|
+
inspected after Launcher returns.
|
|
155
|
+
|
|
156
|
+
## No-Profile Defaults
|
|
157
|
+
|
|
158
|
+
With no profile variables set, commands operate on the user's normal Pharo
|
|
159
|
+
Launcher state scope. pharo-launcher-mcp does not create a hidden default
|
|
160
|
+
profile or redirect images and VMs into its own cache.
|
|
161
|
+
|
|
162
|
+
Detached image launches may write log files under `.pharo-launcher-mcp/logs` in
|
|
163
|
+
the server working directory when no profile log directory is active.
|
|
164
|
+
|
|
165
|
+
## When To Use A Profile
|
|
166
|
+
|
|
167
|
+
Use a profile when the caller needs an isolated Launcher state scope for tests,
|
|
168
|
+
automation, disposable images, or a project-bound runtime. In profile mode,
|
|
169
|
+
image and VM state are separated from the user's normal Launcher installation.
|
|
170
|
+
|
|
171
|
+
Continue with [Profile mode](profile-mode.md) before running live image create,
|
|
172
|
+
launch, delete, or process cleanup calls from automation.
|
|
@@ -0,0 +1,183 @@
|
|
|
1
|
+
# Profile Mode
|
|
2
|
+
|
|
3
|
+
Profiles let pharo-launcher-mcp run Pharo Launcher commands against an explicit
|
|
4
|
+
state scope instead of the user's normal Launcher images, VMs, templates, and
|
|
5
|
+
logs.
|
|
6
|
+
|
|
7
|
+
Use a profile for automation, integration tests, disposable image work, or any
|
|
8
|
+
caller that must keep Launcher state separate from a human's regular Pharo
|
|
9
|
+
Launcher installation.
|
|
10
|
+
|
|
11
|
+
## No-Profile Mode
|
|
12
|
+
|
|
13
|
+
No-profile mode is the default. It is active when none of these environment
|
|
14
|
+
variables are set:
|
|
15
|
+
|
|
16
|
+
```text
|
|
17
|
+
PHARO_LAUNCHER_MCP_PROFILE
|
|
18
|
+
PHARO_LAUNCHER_MCP_STATE_ROOT
|
|
19
|
+
PHARO_LAUNCHER_MCP_LAUNCHER_IMAGE
|
|
20
|
+
PHARO_LAUNCHER_MCP_IMAGES_DIR
|
|
21
|
+
PHARO_LAUNCHER_MCP_VMS_DIR
|
|
22
|
+
PHARO_LAUNCHER_MCP_TEMPLATE_SOURCES_DIR
|
|
23
|
+
PHARO_LAUNCHER_MCP_INIT_SCRIPTS_DIR
|
|
24
|
+
PHARO_LAUNCHER_MCP_LOGS_DIR
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
In this mode, the server uses the resolved Pharo Launcher installation and its
|
|
28
|
+
normal state scope directly. It does not create an implicit profile or choose a
|
|
29
|
+
private image repository.
|
|
30
|
+
|
|
31
|
+
## Minimal Profile
|
|
32
|
+
|
|
33
|
+
The shortest profile setup is a profile name plus a state root:
|
|
34
|
+
|
|
35
|
+
```sh
|
|
36
|
+
PHARO_LAUNCHER_MCP_PROFILE=isolated
|
|
37
|
+
PHARO_LAUNCHER_MCP_STATE_ROOT=/path/to/launcher-profile
|
|
38
|
+
npx @evref-bl/pharo-launcher-mcp --health
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
The server derives the profile layout:
|
|
42
|
+
|
|
43
|
+
```text
|
|
44
|
+
<state-root>/
|
|
45
|
+
launcher/
|
|
46
|
+
PharoLauncher.image
|
|
47
|
+
pharo-launcher-cli-config.ston
|
|
48
|
+
images/
|
|
49
|
+
vms/
|
|
50
|
+
templates/
|
|
51
|
+
init-scripts/
|
|
52
|
+
logs/
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
Before a live Launcher invocation, pharo-launcher-mcp creates those directories,
|
|
56
|
+
copies the installation control image into the profile when needed, copies the
|
|
57
|
+
matching `.changes` file when present, and writes the Launcher CLI
|
|
58
|
+
configuration.
|
|
59
|
+
|
|
60
|
+
## Explicit Profile Paths
|
|
61
|
+
|
|
62
|
+
Callers can also provide every profile path:
|
|
63
|
+
|
|
64
|
+
```sh
|
|
65
|
+
PHARO_LAUNCHER_MCP_LAUNCHER_IMAGE=/path/to/profile/launcher/PharoLauncher.image
|
|
66
|
+
PHARO_LAUNCHER_MCP_IMAGES_DIR=/path/to/profile/images
|
|
67
|
+
PHARO_LAUNCHER_MCP_VMS_DIR=/path/to/profile/vms
|
|
68
|
+
PHARO_LAUNCHER_MCP_TEMPLATE_SOURCES_DIR=/path/to/profile/templates
|
|
69
|
+
PHARO_LAUNCHER_MCP_INIT_SCRIPTS_DIR=/path/to/profile/init-scripts
|
|
70
|
+
PHARO_LAUNCHER_MCP_LOGS_DIR=/path/to/profile/logs
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
`PHARO_LAUNCHER_MCP_LAUNCHER_CONFIGURATION` can point at a custom Launcher CLI
|
|
74
|
+
configuration. In profile mode, a relative value is resolved under
|
|
75
|
+
`<state-root>/launcher`. If it is not set, the server writes
|
|
76
|
+
`<state-root>/launcher/pharo-launcher-cli-config.ston`.
|
|
77
|
+
|
|
78
|
+
The generated configuration sets:
|
|
79
|
+
|
|
80
|
+
- image directory
|
|
81
|
+
- VM directory
|
|
82
|
+
- template source file location
|
|
83
|
+
- init script directory
|
|
84
|
+
- launch-from-login-shell behavior
|
|
85
|
+
|
|
86
|
+
The profile launcher image and generated configuration must stay inside
|
|
87
|
+
`PHARO_LAUNCHER_MCP_STATE_ROOT` when a state root is used. The server refuses to
|
|
88
|
+
write them outside that root.
|
|
89
|
+
|
|
90
|
+
## Template Sources
|
|
91
|
+
|
|
92
|
+
In profile mode, `pharo_launcher_template_update` checks the active profile
|
|
93
|
+
template source file after Launcher returns. If the source file is missing or
|
|
94
|
+
empty, the server seeds it from the default Pharo Launcher source list and then
|
|
95
|
+
probes `template list`.
|
|
96
|
+
|
|
97
|
+
If template listing still fails, inspect:
|
|
98
|
+
|
|
99
|
+
```text
|
|
100
|
+
pharo_launcher_inventory
|
|
101
|
+
pharo_launcher_config
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
The inventory diagnostics include missing or unreadable profile directories and
|
|
105
|
+
configuration files.
|
|
106
|
+
|
|
107
|
+
## Image Launch In Profile Mode
|
|
108
|
+
|
|
109
|
+
For profile-scoped image launch, pharo-launcher-mcp resolves the image inside
|
|
110
|
+
`PHARO_LAUNCHER_MCP_IMAGES_DIR` and runs it with a VM inside
|
|
111
|
+
`PHARO_LAUNCHER_MCP_VMS_DIR`. If the VM is missing, the server asks Launcher to
|
|
112
|
+
install that VM into the profile VM directory before launch.
|
|
113
|
+
|
|
114
|
+
Launch supports:
|
|
115
|
+
|
|
116
|
+
```json
|
|
117
|
+
{
|
|
118
|
+
"imageName": "sample-130",
|
|
119
|
+
"displayMode": "headless",
|
|
120
|
+
"detached": true
|
|
121
|
+
}
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
`displayMode` can be `headless` or `interactive`. Detached launches return the
|
|
125
|
+
spawned PID when available and log paths under the profile log directory.
|
|
126
|
+
|
|
127
|
+
Profile-scoped `pharo_launcher_image_create_from_build` is refused before
|
|
128
|
+
Launcher is invoked. That Launcher path can launch automatically and may use VM
|
|
129
|
+
state outside `PHARO_LAUNCHER_MCP_VMS_DIR`.
|
|
130
|
+
|
|
131
|
+
## Cross-Profile Image Copy
|
|
132
|
+
|
|
133
|
+
`pharo_launcher_image_copy_between_profiles` copies an existing image directory
|
|
134
|
+
from one explicit profile to another without relying on the active server
|
|
135
|
+
profile.
|
|
136
|
+
|
|
137
|
+
Both `sourceProfile` and `destinationProfile` must include either:
|
|
138
|
+
|
|
139
|
+
- `stateRoot`, or
|
|
140
|
+
- the complete explicit path set: `launcherConfiguration`, `imagesDir`,
|
|
141
|
+
`vmsDir`, `templateSourcesDir`, `initScriptsDir`, and `logsDir`.
|
|
142
|
+
|
|
143
|
+
All profile paths must be absolute. Image names must be launcher image names,
|
|
144
|
+
not paths. Destination collisions are refused.
|
|
145
|
+
|
|
146
|
+
Example:
|
|
147
|
+
|
|
148
|
+
```json
|
|
149
|
+
{
|
|
150
|
+
"sourceProfile": {
|
|
151
|
+
"profileName": "source",
|
|
152
|
+
"stateRoot": "/path/to/source-profile"
|
|
153
|
+
},
|
|
154
|
+
"destinationProfile": {
|
|
155
|
+
"profileName": "destination",
|
|
156
|
+
"stateRoot": "/path/to/destination-profile"
|
|
157
|
+
},
|
|
158
|
+
"sourceImageName": "sample-130",
|
|
159
|
+
"destinationImageName": "sample-130-copy"
|
|
160
|
+
}
|
|
161
|
+
```
|
|
162
|
+
|
|
163
|
+
The result reports source and destination image metadata, touched paths,
|
|
164
|
+
metadata repair, verification, and cleanup guidance.
|
|
165
|
+
|
|
166
|
+
A failure adds `message`, one line naming both images, both profiles, what went
|
|
167
|
+
wrong and the way out, next to the `diagnostic` and `action` it is built from.
|
|
168
|
+
A destination that already exists is named by its directory, so the caller can
|
|
169
|
+
read `destinationImage`, adopt what is there, copy under another name, or
|
|
170
|
+
delete it with the destination profile active. An existing image is never
|
|
171
|
+
replaced.
|
|
172
|
+
|
|
173
|
+
## Cleanup Rules
|
|
174
|
+
|
|
175
|
+
Only clean up caller-owned profile state. Keep command envelopes, log files,
|
|
176
|
+
image names, image paths, process PIDs, and timeout reasons long enough to
|
|
177
|
+
debug failed runs.
|
|
178
|
+
|
|
179
|
+
For process cleanup, prefer a recorded PID from a detached launch. For image
|
|
180
|
+
cleanup, delete only image names created by the caller in the active profile.
|
|
181
|
+
|
|
182
|
+
See [Cleanup hook boundary](../cleanup-hook-boundary.md) for the detailed
|
|
183
|
+
status, timeout, stop, and cleanup contract.
|
package/package.json
CHANGED
|
@@ -1,52 +1,59 @@
|
|
|
1
|
-
{
|
|
2
|
-
"name": "@evref-bl/pharo-launcher-mcp",
|
|
3
|
-
"version": "0.1.
|
|
4
|
-
"description": "MCP server for controlling Pharo Launcher images, templates, VMs, and processes.",
|
|
5
|
-
"license": "MIT",
|
|
6
|
-
"type": "module",
|
|
7
|
-
"keywords": [
|
|
8
|
-
"mcp",
|
|
9
|
-
"pharo",
|
|
10
|
-
"pharo-launcher",
|
|
11
|
-
"pharolauncher",
|
|
12
|
-
"smalltalk"
|
|
13
|
-
],
|
|
14
|
-
"bin": {
|
|
15
|
-
"pharo-launcher-mcp": "dist/index.js"
|
|
16
|
-
},
|
|
17
|
-
"
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
"
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
"
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
"
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
"
|
|
38
|
-
"
|
|
39
|
-
"
|
|
40
|
-
"
|
|
41
|
-
"
|
|
42
|
-
"
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
"
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
"
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
}
|
|
1
|
+
{
|
|
2
|
+
"name": "@evref-bl/pharo-launcher-mcp",
|
|
3
|
+
"version": "0.1.4",
|
|
4
|
+
"description": "MCP server for controlling Pharo Launcher images, templates, VMs, and processes.",
|
|
5
|
+
"license": "MIT",
|
|
6
|
+
"type": "module",
|
|
7
|
+
"keywords": [
|
|
8
|
+
"mcp",
|
|
9
|
+
"pharo",
|
|
10
|
+
"pharo-launcher",
|
|
11
|
+
"pharolauncher",
|
|
12
|
+
"smalltalk"
|
|
13
|
+
],
|
|
14
|
+
"bin": {
|
|
15
|
+
"pharo-launcher-mcp": "dist/index.js"
|
|
16
|
+
},
|
|
17
|
+
"repository": {
|
|
18
|
+
"type": "git",
|
|
19
|
+
"url": "git+https://github.com/Evref-BL/pharo-launcher-mcp.git"
|
|
20
|
+
},
|
|
21
|
+
"main": "./dist/index.js",
|
|
22
|
+
"types": "./dist/index.d.ts",
|
|
23
|
+
"files": [
|
|
24
|
+
"bin",
|
|
25
|
+
"docs",
|
|
26
|
+
"dist",
|
|
27
|
+
"LICENSE",
|
|
28
|
+
"README.md"
|
|
29
|
+
],
|
|
30
|
+
"engines": {
|
|
31
|
+
"node": ">=22.12.0"
|
|
32
|
+
},
|
|
33
|
+
"publishConfig": {
|
|
34
|
+
"access": "public"
|
|
35
|
+
},
|
|
36
|
+
"scripts": {
|
|
37
|
+
"check": "npm run typecheck && npm run build && npm test",
|
|
38
|
+
"build": "tsc -p tsconfig.json",
|
|
39
|
+
"prepack": "npm run build",
|
|
40
|
+
"typecheck": "tsc -p tsconfig.json --noEmit",
|
|
41
|
+
"test": "npm run test:unit",
|
|
42
|
+
"test:unit": "vitest run --exclude **/*.integration.test.ts",
|
|
43
|
+
"coverage": "vitest run --exclude **/*.integration.test.ts --coverage --coverage.reporter=text --coverage.reporter=lcov",
|
|
44
|
+
"test:integration": "vitest run src/integration/live.integration.test.ts src/integration/lifecycle.integration.test.ts src/integration/copy.integration.test.ts --testTimeout=900000",
|
|
45
|
+
"clean": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
|
|
46
|
+
"verify:env": "powershell -ExecutionPolicy Bypass -File ./scripts/verify-environment.ps1",
|
|
47
|
+
"live:profile": "powershell -ExecutionPolicy Bypass -File ./scripts/prepare-live-profile.ps1",
|
|
48
|
+
"live:smoke": "powershell -ExecutionPolicy Bypass -File ./scripts/live-smoke.ps1"
|
|
49
|
+
},
|
|
50
|
+
"dependencies": {
|
|
51
|
+
"@modelcontextprotocol/sdk": "^1.29.0"
|
|
52
|
+
},
|
|
53
|
+
"devDependencies": {
|
|
54
|
+
"@types/node": "^22.12.0",
|
|
55
|
+
"@vitest/coverage-v8": "^4.0.0",
|
|
56
|
+
"typescript": "^5.9.0",
|
|
57
|
+
"vitest": "^4.0.0"
|
|
58
|
+
}
|
|
59
|
+
}
|