@evref-bl/pharo-launcher-mcp 0.1.3 → 0.2.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 (48) hide show
  1. package/README.md +30 -38
  2. package/dist/commandCatalog.d.ts +0 -2
  3. package/dist/commandCatalog.d.ts.map +1 -1
  4. package/dist/commandCatalog.js +18 -279
  5. package/dist/commandCatalog.js.map +1 -1
  6. package/dist/crossProfileCopy.d.ts +1 -0
  7. package/dist/crossProfileCopy.d.ts.map +1 -1
  8. package/dist/crossProfileCopy.js +107 -14
  9. package/dist/crossProfileCopy.js.map +1 -1
  10. package/dist/discovery.d.ts +0 -151
  11. package/dist/discovery.d.ts.map +1 -1
  12. package/dist/discovery.js +31 -702
  13. package/dist/discovery.js.map +1 -1
  14. package/dist/launcherCli.d.ts.map +1 -1
  15. package/dist/launcherCli.js +94 -103
  16. package/dist/launcherCli.js.map +1 -1
  17. package/dist/launcherScript.d.ts +0 -1
  18. package/dist/launcherScript.d.ts.map +1 -1
  19. package/dist/launcherScript.js.map +1 -1
  20. package/dist/models.d.ts +1 -9
  21. package/dist/models.d.ts.map +1 -1
  22. package/dist/parser.d.ts +1 -3
  23. package/dist/parser.d.ts.map +1 -1
  24. package/dist/parser.js +58 -53
  25. package/dist/parser.js.map +1 -1
  26. package/dist/processTools.d.ts.map +1 -1
  27. package/dist/processTools.js +25 -11
  28. package/dist/processTools.js.map +1 -1
  29. package/dist/resultNormalizer.d.ts +5 -1
  30. package/dist/resultNormalizer.d.ts.map +1 -1
  31. package/dist/resultNormalizer.js +36 -21
  32. package/dist/resultNormalizer.js.map +1 -1
  33. package/dist/server.d.ts +1 -0
  34. package/dist/server.d.ts.map +1 -1
  35. package/dist/server.js +111 -243
  36. package/dist/server.js.map +1 -1
  37. package/dist/textTokens.d.ts +10 -0
  38. package/dist/textTokens.d.ts.map +1 -0
  39. package/dist/textTokens.js +68 -0
  40. package/dist/textTokens.js.map +1 -0
  41. package/docs/README.md +1 -1
  42. package/docs/cleanup-hook-boundary.md +5 -8
  43. package/docs/development.md +7 -1
  44. package/docs/reference/tools.md +33 -76
  45. package/docs/troubleshooting.md +11 -18
  46. package/docs/user/getting-started.md +8 -16
  47. package/docs/user/profile-mode.md +12 -8
  48. package/package.json +12 -4
@@ -13,16 +13,15 @@ These checks are safe for planning and static verification:
13
13
  - `git status --short --branch`
14
14
  - source review of command schemas, parser behavior, result envelopes, and
15
15
  timeout handling
16
- - `pharo_launcher_health`, because it reports resolved paths without invoking
17
- Pharo Launcher
16
+ - `pharo-launcher-mcp --health`, because it reports resolved paths without
17
+ invoking Pharo Launcher
18
18
  - `pharo_launcher_config`, because it reports resolved configuration without
19
19
  invoking Pharo Launcher
20
20
 
21
21
  These checks inspect live host state or invoke Pharo Launcher. Run them only
22
22
  when the caller has chosen to cross that boundary:
23
23
 
24
- - `pharo_launcher_version`
25
- - `pharo_launcher_validate_installation`
24
+ - `pharo-launcher-mcp --version-check` and `--validate-installation`
26
25
  - `pharo_launcher_image_list`
27
26
  - `pharo_launcher_image_info`
28
27
  - `pharo_launcher_process_list`
@@ -49,10 +48,8 @@ Raw output is diagnostic evidence, not ownership proof.
49
48
 
50
49
  The mutation hooks that can participate in cleanup are:
51
50
 
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
51
+ - `pharo_launcher_process_kill`
52
+ - `pharo_launcher_image_delete`
56
53
  - profile-root cleanup by the caller after logs and diagnostics are retained
57
54
 
58
55
  The caller must pass either a recorded pid or an owned image name. Ambiguous
@@ -37,6 +37,12 @@ npm run test:integration
37
37
  `npm run check` runs type checking, build, and unit tests. `npm test` runs unit
38
38
  coverage only. It does not invoke a local Pharo Launcher.
39
39
 
40
+ Type checking reads `tsconfig.check.json`, which covers the unit and
41
+ integration tests as well as the production code; the build reads
42
+ `tsconfig.json`, which leaves the tests out of `dist`. The integration tests
43
+ need a live Pharo Launcher to run, so type checking is the only thing that
44
+ reads them on CI.
45
+
40
46
  ## Platform contract
41
47
 
42
48
  The production code handles Windows, macOS, and Linux explicitly:
@@ -131,7 +137,7 @@ the Pharo Launcher control image. It includes live checks for:
131
137
  - image delete
132
138
  - process list
133
139
  - process kill
134
- - raw command with explicit confirmation
140
+ - raw command
135
141
 
136
142
  External-source image creation variants such as build, pull request,
137
143
  repository, SHA, and VM mutation commands should use explicit fixtures because
@@ -1,33 +1,21 @@
1
1
  # Tool Reference
2
2
 
3
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.
4
+ and return a normalized launcher result envelope.
6
5
 
7
- ## Health And Configuration
6
+ Every tool here has a caller. PharoLauncher's CLI covers the rest of its own
7
+ surface, and this server does not wrap a subcommand until something asks it to.
8
+
9
+ Checking the installation is not a tool, because a caller doing it is not yet
10
+ speaking MCP. The executable answers `--health`, `--version-check`,
11
+ `--validate-installation` and `--probe-images` and exits, which is what a
12
+ preflight needs.
13
+
14
+ ## Configuration
8
15
 
9
16
  | Tool | Live Launcher invocation | Purpose |
10
17
  | --- | --- | --- |
11
- | `pharo_launcher_health` | No | Reports service version, resolved paths, wrapper source, and existence checks. |
12
18
  | `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
19
 
32
20
  ## Image Tools
33
21
 
@@ -38,23 +26,18 @@ scoped caller:
38
26
  | `pharo_launcher_image_create` | `templateName`, `newImageName`, `templateCategory`, `dev`, `noLaunch` |
39
27
  | `pharo_launcher_image_copy` | `imageName`, `newImageName` |
40
28
  | `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` |
29
+ | `pharo_launcher_image_start` | `imageName`, `script`, `detached`, `displayMode` |
30
+ | `pharo_launcher_image_delete` | `imageName`, `force` |
50
31
 
51
32
  `pharo_launcher_image_create` and `pharo_launcher_image_copy` verify the target
52
33
  image after Launcher returns. A successful Launcher exit is not enough: the MCP
53
34
  result is successful only when the target image can be listed and inspected.
54
35
 
55
- `pharo_launcher_image_launch` supports:
36
+ `pharo_launcher_image_start` supports:
56
37
 
57
- - `displayMode: "headless"` or `"interactive"`
38
+ - `displayMode: "headless"` or `"interactive"`, in profile mode only.
39
+ PharoLauncher's own `image launch` has no display mode, so outside profile
40
+ mode the launch is refused rather than started with the mode dropped.
58
41
  - `detached: true` for detached launches with log paths in the result
59
42
  - `script` for a launch script passed to Launcher, or evaluated by the profile
60
43
  VM launch path
@@ -68,7 +51,6 @@ profile roots instead of using Launcher defaults.
68
51
  | --- | --- |
69
52
  | `pharo_launcher_template_category_list` | table options |
70
53
  | `pharo_launcher_template_list` | `templateCategory`, table options |
71
- | `pharo_launcher_template_info` | `templateName`, `templateCategory` |
72
54
  | `pharo_launcher_template_update` | none |
73
55
 
74
56
  Table options are:
@@ -88,46 +70,24 @@ table output.
88
70
  In profile mode, `pharo_launcher_template_update` also verifies that the active
89
71
  profile source list is usable and probes `template list`.
90
72
 
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
73
  ## Process Tools
104
74
 
105
75
  | Tool | Arguments |
106
76
  | --- | --- |
107
77
  | `pharo_launcher_process_list` | none |
108
- | `pharo_launcher_process_kill` | exactly one of `pid` or `imageName`, plus `confirm: true` |
78
+ | `pharo_launcher_process_kill` | exactly one of `pid` or `imageName` |
109
79
 
110
80
  On Windows, process tools use PowerShell/CIM. On macOS and Linux, they use
111
81
  `ps -axo pid=,args=`. Unsupported platforms return an explicit unsupported
112
82
  backend error.
113
83
 
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
84
+ A kill matches the target it was given. An all-digit target is a PID and
85
+ matches that process only. Any other target is an image, and matches a process
86
+ whose image name or image path is exactly that. An image launched more than
87
+ once has more than one process, so an image-name kill can still stop several.
119
88
 
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`.
89
+ Prefer the PID returned by a prior detached launch when cleaning up a launch
90
+ you own.
131
91
 
132
92
  ## Result Envelope
133
93
 
@@ -162,18 +122,15 @@ Launcher tools return JSON shaped like this:
162
122
  Use `ok` and normalized `data` for program flow. Treat `raw.stdout` and
163
123
  `raw.stderr` as diagnostics.
164
124
 
165
- ## Confirmation Gates
125
+ ## Mutation Boundary
166
126
 
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
- ```
127
+ No tool takes a confirmation argument. A confirmation could only say that the
128
+ caller meant to call the tool, which calling it already says; it never proved
129
+ the image, VM, profile, or process was caller-owned, and that is the thing
130
+ worth knowing.
176
131
 
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.
132
+ Deciding what is caller-owned is the caller's job. What this server offers
133
+ towards it: `pharo_launcher_image_list` for what exists,
134
+ `pharo_launcher_process_list` for what runs, profile scoping for keeping a
135
+ caller's images and VMs out of the user's own Launcher state, and targets that
136
+ mean one thing — a PID stops one process.
@@ -1,6 +1,6 @@
1
1
  # Troubleshooting
2
2
 
3
- Start with `pharo_launcher_health` or the local CLI health check:
3
+ Start with the executable's own health check:
4
4
 
5
5
  ```sh
6
6
  npx @evref-bl/pharo-launcher-mcp --health
@@ -41,12 +41,12 @@ If a selected wrapper path exists but is not executable, the command result
41
41
  contains a startup diagnostic with the command, args, working directory, PATH,
42
42
  and active profile variables.
43
43
 
44
- ## `validate_installation` Fails
44
+ ## Installation Validation Fails
45
45
 
46
- `pharo_launcher_validate_installation` runs `--version`. If it fails:
46
+ `pharo-launcher-mcp --validate-installation` runs `--version`. If it fails:
47
47
 
48
48
  1. Run `pharo_launcher_config` and confirm the VM and control image paths.
49
- 2. Run `pharo_launcher_health` and check `launcherScript.exists`.
49
+ 2. Run `pharo-launcher-mcp --health` and check `launcherScript.exists`.
50
50
  3. If using a profile, confirm the installation control image exists. The
51
51
  profile control image is copied from that source before live commands.
52
52
  4. Try `node ./dist/index.js --version-check` from a local build to separate MCP
@@ -78,12 +78,12 @@ Run:
78
78
 
79
79
  ```text
80
80
  pharo_launcher_template_update
81
- pharo_launcher_inventory
81
+ 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`. Inventory diagnostics report
86
- missing profile directories, missing configuration files, and failed probes.
85
+ missing or empty, then probes `template list`. Its diagnostics report missing
86
+ profile directories, missing configuration files, and failed probes.
87
87
 
88
88
  ## Image Create Or Copy Reports An Error After Launcher Succeeds
89
89
 
@@ -109,9 +109,10 @@ Process tools use native host process queries:
109
109
  - macOS and Linux: `ps -axo pid=,args=`
110
110
 
111
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.
112
+ path. For cleanup, prefer a PID captured from the detached launch result, which
113
+ stops that process and nothing else. An `imageName` has to match the process's
114
+ image name or image path exactly, so an image that is not listed by
115
+ `pharo_launcher_process_list` under that exact name will not be found.
115
116
 
116
117
  ## Commands Time Out
117
118
 
@@ -125,11 +126,3 @@ Every Launcher command is bounded by a timeout. Timeout results include:
125
126
  A timeout does not authorize broader host cleanup. Cleanup should use only
126
127
  recorded image names, profile roots, and PIDs that the caller owns.
127
128
 
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.
@@ -110,25 +110,17 @@ client entry. See [Profile mode](profile-mode.md).
110
110
 
111
111
  ## First Tools
112
112
 
113
- Run read-only checks first:
113
+ Check the installation from the command line, before connecting a client:
114
114
 
115
- ```text
116
- pharo_launcher_health
117
- pharo_launcher_config
118
- pharo_launcher_validate_installation
119
- pharo_launcher_inventory
115
+ ```sh
116
+ npx @evref-bl/pharo-launcher-mcp --health
117
+ npx @evref-bl/pharo-launcher-mcp --validate-installation
120
118
  ```
121
119
 
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.
120
+ `--health` confirms whether the resolved directory, VM, control image, and
121
+ wrapper exist, without invoking Pharo Launcher. `--validate-installation` runs
122
+ `--version` and verifies that the launcher command can start. Connected,
123
+ `pharo_launcher_config` reports the same resolved configuration.
132
124
 
133
125
  After validation, list templates:
134
126
 
@@ -97,11 +97,10 @@ probes `template list`.
97
97
  If template listing still fails, inspect:
98
98
 
99
99
  ```text
100
- pharo_launcher_inventory
101
100
  pharo_launcher_config
102
101
  ```
103
102
 
104
- The inventory diagnostics include missing or unreadable profile directories and
103
+ Its report includes missing or unreadable profile directories and
105
104
  configuration files.
106
105
 
107
106
  ## Image Launch In Profile Mode
@@ -121,12 +120,10 @@ Launch supports:
121
120
  }
122
121
  ```
123
122
 
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`.
123
+ `displayMode` can be `headless` or `interactive`, and only here: PharoLauncher's
124
+ own `image launch` has no display mode, so outside profile mode a launch that
125
+ asks for one is refused. Detached launches return the spawned PID and log paths
126
+ under the profile log directory.
130
127
 
131
128
  ## Cross-Profile Image Copy
132
129
 
@@ -163,6 +160,13 @@ Example:
163
160
  The result reports source and destination image metadata, touched paths,
164
161
  metadata repair, verification, and cleanup guidance.
165
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
167
+ delete it with the destination profile active. An existing image is never
168
+ replaced.
169
+
166
170
  ## Cleanup Rules
167
171
 
168
172
  Only clean up caller-owned profile state. Keep command envelopes, log files,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@evref-bl/pharo-launcher-mcp",
3
- "version": "0.1.3",
3
+ "version": "0.2.0",
4
4
  "description": "MCP server for controlling Pharo Launcher images, templates, VMs, and processes.",
5
5
  "license": "MIT",
6
6
  "type": "module",
@@ -18,8 +18,14 @@
18
18
  "type": "git",
19
19
  "url": "git+https://github.com/Evref-BL/pharo-launcher-mcp.git"
20
20
  },
21
- "main": "./dist/index.js",
22
- "types": "./dist/index.d.ts",
21
+ "main": "./dist/server.js",
22
+ "types": "./dist/server.d.ts",
23
+ "exports": {
24
+ ".": "./dist/server.js",
25
+ "./config": "./dist/config.js",
26
+ "./platform": "./dist/platform.js",
27
+ "./package.json": "./package.json"
28
+ },
23
29
  "files": [
24
30
  "bin",
25
31
  "docs",
@@ -37,9 +43,10 @@
37
43
  "check": "npm run typecheck && npm run build && npm test",
38
44
  "build": "tsc -p tsconfig.json",
39
45
  "prepack": "npm run build",
40
- "typecheck": "tsc -p tsconfig.json --noEmit",
46
+ "typecheck": "tsc -p tsconfig.check.json",
41
47
  "test": "npm run test:unit",
42
48
  "test:unit": "vitest run --exclude **/*.integration.test.ts",
49
+ "coverage": "vitest run --exclude **/*.integration.test.ts --coverage --coverage.reporter=text --coverage.reporter=lcov",
43
50
  "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
51
  "clean": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
45
52
  "verify:env": "powershell -ExecutionPolicy Bypass -File ./scripts/verify-environment.ps1",
@@ -51,6 +58,7 @@
51
58
  },
52
59
  "devDependencies": {
53
60
  "@types/node": "^22.12.0",
61
+ "@vitest/coverage-v8": "^4.0.0",
54
62
  "typescript": "^5.9.0",
55
63
  "vitest": "^4.0.0"
56
64
  }