@evref-bl/pharo-launcher-mcp 0.1.2 → 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 +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 +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 +75 -6
- 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 +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 +561 -62
- 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 +47 -0
- package/dist/resultNormalizer.js.map +1 -1
- package/dist/server.d.ts +2 -0
- package/dist/server.d.ts.map +1 -1
- package/dist/server.js +387 -10
- 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 +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 +176 -0
- package/package.json +57 -52
|
@@ -0,0 +1,176 @@
|
|
|
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
|
+
## Cleanup Rules
|
|
167
|
+
|
|
168
|
+
Only clean up caller-owned profile state. Keep command envelopes, log files,
|
|
169
|
+
image names, image paths, process PIDs, and timeout reasons long enough to
|
|
170
|
+
debug failed runs.
|
|
171
|
+
|
|
172
|
+
For process cleanup, prefer a recorded PID from a detached launch. For image
|
|
173
|
+
cleanup, delete only image names created by the caller in the active profile.
|
|
174
|
+
|
|
175
|
+
See [Cleanup hook boundary](../cleanup-hook-boundary.md) for the detailed
|
|
176
|
+
status, timeout, stop, and cleanup contract.
|
package/package.json
CHANGED
|
@@ -1,52 +1,57 @@
|
|
|
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.3",
|
|
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
|
+
"test:integration": "vitest run src/integration/live.integration.test.ts src/integration/lifecycle.integration.test.ts src/integration/copy.integration.test.ts --testTimeout=900000",
|
|
44
|
+
"clean": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
|
|
45
|
+
"verify:env": "powershell -ExecutionPolicy Bypass -File ./scripts/verify-environment.ps1",
|
|
46
|
+
"live:profile": "powershell -ExecutionPolicy Bypass -File ./scripts/prepare-live-profile.ps1",
|
|
47
|
+
"live:smoke": "powershell -ExecutionPolicy Bypass -File ./scripts/live-smoke.ps1"
|
|
48
|
+
},
|
|
49
|
+
"dependencies": {
|
|
50
|
+
"@modelcontextprotocol/sdk": "^1.29.0"
|
|
51
|
+
},
|
|
52
|
+
"devDependencies": {
|
|
53
|
+
"@types/node": "^22.12.0",
|
|
54
|
+
"typescript": "^5.9.0",
|
|
55
|
+
"vitest": "^4.0.0"
|
|
56
|
+
}
|
|
57
|
+
}
|