@evref-bl/pharo-launcher-mcp 0.4.0 → 0.5.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 (72) hide show
  1. package/README.md +29 -20
  2. package/dist/answers.d.ts +43 -0
  3. package/dist/answers.d.ts.map +1 -0
  4. package/dist/answers.js +744 -0
  5. package/dist/answers.js.map +1 -0
  6. package/dist/commandCatalog.d.ts +13 -1
  7. package/dist/commandCatalog.d.ts.map +1 -1
  8. package/dist/commandCatalog.js +65 -89
  9. package/dist/commandCatalog.js.map +1 -1
  10. package/dist/config.d.ts +5 -0
  11. package/dist/config.d.ts.map +1 -1
  12. package/dist/config.js +3 -1
  13. package/dist/config.js.map +1 -1
  14. package/dist/crossProfileCopy.d.ts +37 -0
  15. package/dist/crossProfileCopy.d.ts.map +1 -1
  16. package/dist/crossProfileCopy.js +77 -16
  17. package/dist/crossProfileCopy.js.map +1 -1
  18. package/dist/discovery.d.ts +8 -0
  19. package/dist/discovery.d.ts.map +1 -1
  20. package/dist/discovery.js +10 -0
  21. package/dist/discovery.js.map +1 -1
  22. package/dist/imageStore.d.ts +139 -0
  23. package/dist/imageStore.d.ts.map +1 -0
  24. package/dist/imageStore.js +385 -0
  25. package/dist/imageStore.js.map +1 -0
  26. package/dist/index.js +4 -4
  27. package/dist/index.js.map +1 -1
  28. package/dist/launcher.d.ts +64 -17
  29. package/dist/launcher.d.ts.map +1 -1
  30. package/dist/launcher.js +206 -167
  31. package/dist/launcher.js.map +1 -1
  32. package/dist/launcherCli.d.ts +13 -0
  33. package/dist/launcherCli.d.ts.map +1 -1
  34. package/dist/launcherCli.js +85 -91
  35. package/dist/launcherCli.js.map +1 -1
  36. package/dist/models.d.ts +117 -6
  37. package/dist/models.d.ts.map +1 -1
  38. package/dist/parser.d.ts +20 -7
  39. package/dist/parser.d.ts.map +1 -1
  40. package/dist/parser.js +48 -207
  41. package/dist/parser.js.map +1 -1
  42. package/dist/platform.d.ts +6 -0
  43. package/dist/platform.d.ts.map +1 -1
  44. package/dist/platform.js +14 -0
  45. package/dist/platform.js.map +1 -1
  46. package/dist/probe.d.ts +16 -0
  47. package/dist/probe.d.ts.map +1 -0
  48. package/dist/probe.js +31 -0
  49. package/dist/probe.js.map +1 -0
  50. package/dist/processTools.d.ts +22 -8
  51. package/dist/processTools.d.ts.map +1 -1
  52. package/dist/processTools.js +75 -58
  53. package/dist/processTools.js.map +1 -1
  54. package/dist/resultNormalizer.d.ts +9 -0
  55. package/dist/resultNormalizer.d.ts.map +1 -1
  56. package/dist/resultNormalizer.js +36 -79
  57. package/dist/resultNormalizer.js.map +1 -1
  58. package/dist/server.d.ts +10 -9
  59. package/dist/server.d.ts.map +1 -1
  60. package/dist/server.js +56 -55
  61. package/dist/server.js.map +1 -1
  62. package/dist/ston.d.ts +22 -0
  63. package/dist/ston.d.ts.map +1 -0
  64. package/dist/ston.js +127 -0
  65. package/dist/ston.js.map +1 -0
  66. package/docs/cleanup-hook-boundary.md +11 -9
  67. package/docs/development.md +51 -38
  68. package/docs/reference/tools.md +100 -40
  69. package/docs/troubleshooting.md +32 -23
  70. package/docs/user/getting-started.md +4 -4
  71. package/docs/user/profile-mode.md +30 -21
  72. package/package.json +1 -1
package/README.md CHANGED
@@ -45,12 +45,13 @@ import { openPharoLauncher } from "@evref-bl/pharo-launcher-mcp/launcher";
45
45
 
46
46
  const launcher = openPharoLauncher();
47
47
  const running = await launcher.listProcesses();
48
- const images = await launcher.listImages({ nameFilter: "Task" });
48
+ const { imagesDir, images, notImages } = await launcher.listImages({ nameFilter: "Task" });
49
49
  ```
50
50
 
51
- Each call answers the normalized launcher result directly, with its `ok`,
52
- `data`, `diagnostic` and `command` fields typed, rather than JSON inside an MCP
53
- text block that the caller parses back.
51
+ Each call answers a typed object, which the MCP tools only render as text.
52
+ `listImages` reads the images directory and answers `{ imagesDir, images,
53
+ notImages }`; a function that runs a Launcher command answers the launcher
54
+ result, with its `ok`, `data`, `diagnostic` and `command` fields.
54
55
 
55
56
  A TypeScript caller gets those shapes with them, so a result does not have to
56
57
  be described a second time on the way out:
@@ -59,6 +60,7 @@ be described a second time on the way out:
59
60
  import type {
60
61
  LauncherCommandResult,
61
62
  LauncherImage,
63
+ LauncherImageList,
62
64
  LauncherProcess,
63
65
  LauncherTemplate,
64
66
  } from "@evref-bl/pharo-launcher-mcp/launcher";
@@ -96,9 +98,12 @@ server on stdio.
96
98
  state scope directly.
97
99
  - A **pharo-launcher-mcp profile** is an explicit isolated state scope selected
98
100
  through environment variables.
99
- - A **launcher tool result** is the normalized JSON envelope returned by most
100
- tools. It includes parsed data when available, raw stdout/stderr, parser
101
- status, command duration, exit code, and timeout state.
101
+ - An **image** is a directory `D` of the Launcher's images directory holding
102
+ `D.image` and `D.changes`, Pharo Launcher's own rule.
103
+ - A **launcher result** is the object the library's functions answer for a
104
+ Launcher command: parsed data when available, raw stdout/stderr when asked
105
+ for, parser status, command duration, exit code, and timeout state. The MCP
106
+ tools answer plain text rendered from it, for a model to read.
102
107
 
103
108
  ## Quick Start
104
109
 
@@ -139,12 +144,15 @@ pharo_launcher_image_list
139
144
  pharo_launcher_template_list
140
145
  ```
141
146
 
142
- `pharo_launcher_config` only inspects resolved configuration; the other two
143
- cross the live Launcher boundary.
147
+ `pharo_launcher_config` only inspects resolved configuration, and
148
+ `pharo_launcher_image_list` reads the images directory; the template list
149
+ crosses the live Launcher boundary.
144
150
 
145
151
  Checking the installation before connecting is the executable's job, not a
146
- tool's. `pharo-launcher-mcp --health`, `--version-check`,
147
- `--validate-installation` and `--probe-images` each print JSON and exit.
152
+ tool's. `pharo-launcher-mcp --health`, `--version-check` and
153
+ `--validate-installation` each print JSON and exit. `--probe-images` asks the
154
+ Launcher to list its images, exits with that command's status, and prints what
155
+ `pharo_launcher_image_list` answers.
148
156
 
149
157
  ## Profile Quick Start
150
158
 
@@ -181,8 +189,7 @@ Create an image from a template:
181
189
  "tool": "pharo_launcher_image_create",
182
190
  "arguments": {
183
191
  "templateName": "Pharo 13.0 - 64bit",
184
- "newImageName": "sample-130",
185
- "noLaunch": true
192
+ "newImageName": "sample-130"
186
193
  }
187
194
  }
188
195
  ```
@@ -221,12 +228,14 @@ spelling of the same intent protects nothing.
221
228
  What does protect something is the target. `pharo_launcher_process_kill`
222
229
  requires exactly one of `pid` or `imageName`, and a PID stops that process
223
230
  alone. Prefer the PID a detached launch returned when cleaning up a launch you
224
- own.
231
+ own. The process tools see only the VMs running an image of this Launcher's
232
+ images directory, so a kill cannot reach another Launcher's image.
233
+ `pharo_launcher_image_delete` refuses an image that a VM runs.
225
234
 
226
- `pharo_launcher_image_create` and `pharo_launcher_image_copy` verify the target
227
- image after Launcher reports success. If the target image cannot be listed and
228
- inspected, the MCP result is an error with the command output and verification
229
- diagnostics.
235
+ `pharo_launcher_image_create` and `pharo_launcher_image_copy` check that the
236
+ Launcher can list the new image and open it, even after a command that outlived
237
+ the call's timeout. If it cannot, the answer is an error saying which check
238
+ failed.
230
239
 
231
240
  ## Documentation
232
241
 
@@ -235,8 +244,8 @@ diagnostics.
235
244
  - [Profile mode](docs/user/profile-mode.md) explains no-profile mode, isolated
236
245
  profiles, profile paths, generated configuration, and cross-profile image
237
246
  copy.
238
- - [Tool reference](docs/reference/tools.md) lists the MCP tools, arguments,
239
- result envelope, and special behaviors.
247
+ - [Tool reference](docs/reference/tools.md) lists the MCP tools, their
248
+ arguments and answers, the library's results, and special behaviors.
240
249
  - [Troubleshooting](docs/troubleshooting.md) maps common setup and live Launcher
241
250
  failures to concrete checks.
242
251
  - [Development](docs/development.md) covers source layout, tests, local probes,
@@ -0,0 +1,43 @@
1
+ import { ToolInputError } from "./commandCatalog.js";
2
+ import type { PharoLauncherConfig } from "./config.js";
3
+ import { type CallToolOptions, type PharoLauncher } from "./launcher.js";
4
+ export type ToolResult = {
5
+ content: Array<{
6
+ type: "text";
7
+ text: string;
8
+ }>;
9
+ isError?: boolean;
10
+ };
11
+ /** What one call has to hand: the launcher it opened, and the scope it runs in. */
12
+ export interface AnswerContext {
13
+ launcher: PharoLauncher;
14
+ config: PharoLauncherConfig;
15
+ options: CallToolOptions;
16
+ /** Where this server reads images, as it resolves the path. */
17
+ imagesDir: string;
18
+ }
19
+ type Answer = (context: AnswerContext, input: Record<string, unknown>) => Promise<ToolResult>;
20
+ declare function failure(...lines: ReadonlyArray<string | undefined | false>): ToolResult;
21
+ /**
22
+ * A value that carries whitespace, quoted so that where it ends is never a
23
+ * guess, `"` and `\` escaped: `MCPTool>>inlineValueTextFor:`.
24
+ */
25
+ export declare function inlineValue(value: string): string;
26
+ /** The Pharo version as Pharo says it: "140" is 14.0 and "61" is 6.1; anything else as it is. */
27
+ export declare function pharoVersionText(raw: string | undefined): string | undefined;
28
+ /** The answer of each tool, by name: the table PLexus mirrors with functions. */
29
+ export declare const toolAnswers: Readonly<Record<string, Answer>>;
30
+ /**
31
+ * Only the arguments a tool's schema names. One it never took is refused,
32
+ * as MCP and PLexus refuse it; one an earlier release took is dropped.
33
+ */
34
+ export declare function toolArguments(schema: {
35
+ properties?: Record<string, unknown>;
36
+ }, argumentsValue: unknown): Record<string, unknown>;
37
+ /** `Invalid arguments for <tool>. <the error.> It takes <its arguments>.` */
38
+ export declare function invalidArgumentsText(toolName: string, schema: {
39
+ properties?: Record<string, unknown>;
40
+ }, error: ToolInputError): string;
41
+ export declare function unknownToolText(toolName: string): string;
42
+ export { failure as failureResult };
43
+ //# sourceMappingURL=answers.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"answers.d.ts","sourceRoot":"","sources":["../src/answers.ts"],"names":[],"mappings":"AAcA,OAAO,EAKL,cAAc,EACf,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAQvD,OAAO,EAGL,KAAK,eAAe,EACpB,KAAK,aAAa,EAEnB,MAAM,eAAe,CAAC;AAYvB,MAAM,MAAM,UAAU,GAAG;IACvB,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC/C,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB,CAAC;AAEF,mFAAmF;AACnF,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,aAAa,CAAC;IACxB,MAAM,EAAE,mBAAmB,CAAC;IAC5B,OAAO,EAAE,eAAe,CAAC;IACzB,+DAA+D;IAC/D,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,KAAK,MAAM,GAAG,CAAC,OAAO,EAAE,aAAa,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,UAAU,CAAC,CAAC;AAgB9F,iBAAS,OAAO,CAAC,GAAG,KAAK,EAAE,aAAa,CAAC,MAAM,GAAG,SAAS,GAAG,KAAK,CAAC,GAAG,UAAU,CAEhF;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEjD;AAoND,iGAAiG;AACjG,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAE5E;AA+mBD,iFAAiF;AACjF,eAAO,MAAM,WAAW,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAcxD,CAAC;AAkBF;;;GAGG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE;IAAE,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,EAChD,cAAc,EAAE,OAAO,GACtB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAYzB;AAED,6EAA6E;AAC7E,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE;IAAE,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,EAChD,KAAK,EAAE,cAAc,GACpB,MAAM,CAMR;AAED,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAExD;AAED,OAAO,EAAE,OAAO,IAAI,aAAa,EAAE,CAAC"}