@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.
Files changed (47) hide show
  1. package/README.md +229 -199
  2. package/bin/pharo-launcher.cmd +46 -46
  3. package/bin/pharo-launcher.sh +0 -0
  4. package/dist/commandCatalog.d.ts.map +1 -1
  5. package/dist/commandCatalog.js +17 -0
  6. package/dist/commandCatalog.js.map +1 -1
  7. package/dist/config.d.ts +21 -1
  8. package/dist/config.d.ts.map +1 -1
  9. package/dist/config.js +75 -6
  10. package/dist/config.js.map +1 -1
  11. package/dist/crossProfileCopy.d.ts +87 -0
  12. package/dist/crossProfileCopy.d.ts.map +1 -0
  13. package/dist/crossProfileCopy.js +437 -0
  14. package/dist/crossProfileCopy.js.map +1 -0
  15. package/dist/discovery.d.ts +165 -1
  16. package/dist/discovery.d.ts.map +1 -1
  17. package/dist/discovery.js +744 -1
  18. package/dist/discovery.js.map +1 -1
  19. package/dist/imageMetadata.d.ts +1 -0
  20. package/dist/imageMetadata.d.ts.map +1 -1
  21. package/dist/imageMetadata.js +35 -2
  22. package/dist/imageMetadata.js.map +1 -1
  23. package/dist/launcherCli.d.ts +2 -0
  24. package/dist/launcherCli.d.ts.map +1 -1
  25. package/dist/launcherCli.js +561 -62
  26. package/dist/launcherCli.js.map +1 -1
  27. package/dist/models.d.ts +2 -0
  28. package/dist/models.d.ts.map +1 -1
  29. package/dist/platform.d.ts +2 -0
  30. package/dist/platform.d.ts.map +1 -1
  31. package/dist/platform.js +21 -0
  32. package/dist/platform.js.map +1 -1
  33. package/dist/resultNormalizer.d.ts.map +1 -1
  34. package/dist/resultNormalizer.js +47 -0
  35. package/dist/resultNormalizer.js.map +1 -1
  36. package/dist/server.d.ts +2 -0
  37. package/dist/server.d.ts.map +1 -1
  38. package/dist/server.js +387 -10
  39. package/dist/server.js.map +1 -1
  40. package/docs/README.md +26 -0
  41. package/docs/cleanup-hook-boundary.md +94 -0
  42. package/docs/development.md +59 -23
  43. package/docs/reference/tools.md +179 -0
  44. package/docs/troubleshooting.md +135 -0
  45. package/docs/user/getting-started.md +172 -0
  46. package/docs/user/profile-mode.md +176 -0
  47. 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.2",
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
- "main": "./dist/index.js",
18
- "types": "./dist/index.d.ts",
19
- "files": [
20
- "bin",
21
- "docs/development.md",
22
- "dist",
23
- "LICENSE",
24
- "README.md"
25
- ],
26
- "engines": {
27
- "node": ">=24"
28
- },
29
- "publishConfig": {
30
- "access": "public"
31
- },
32
- "scripts": {
33
- "build": "tsc -p tsconfig.json",
34
- "prepack": "npm run build",
35
- "typecheck": "tsc -p tsconfig.json --noEmit",
36
- "test": "npm run test:unit",
37
- "test:unit": "vitest run --exclude **/*.integration.test.ts",
38
- "test:integration": "vitest run src/integration/live.integration.test.ts src/integration/lifecycle.integration.test.ts src/integration/copy.integration.test.ts --testTimeout=900000",
39
- "clean": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
40
- "verify:env": "powershell -ExecutionPolicy Bypass -File ./scripts/verify-environment.ps1",
41
- "live:profile": "powershell -ExecutionPolicy Bypass -File ./scripts/prepare-live-profile.ps1",
42
- "live:smoke": "powershell -ExecutionPolicy Bypass -File ./scripts/live-smoke.ps1"
43
- },
44
- "dependencies": {
45
- "@modelcontextprotocol/sdk": "^1.29.0"
46
- },
47
- "devDependencies": {
48
- "@types/node": "^24.0.0",
49
- "typescript": "^5.9.0",
50
- "vitest": "^4.0.0"
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
+ }