@evref-bl/pharo-agent 0.5.5 → 0.6.0

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "pharo-agent",
   "displayName": "Pharo Agent",
-  "version": "0.5.5",
+  "version": "0.6.0",
   "description": "Terminal-first Pharo image setup for coding agents.",
   "author": {
     "name": "Evref-BL",

package/README.md

@@ -17,6 +17,20 @@ workflow skills that guidance refers to. From there the agent registers the
 image the project needs, opens it and uses its tools by following what was
 written; ask it for Pharo work as you would for anything else.
 
+## Refreshing an existing project
+
+After upgrading the plugin/CLI through your usual installation method, re-run
+`pharo-agent init --host <claude|codex|opencode>` from the project root with
+the same host. This refreshes the generated guidance, skills, and references
+using that CLI version's pinned templates. Image declarations, existing plugin
+settings, and guidance outside the host's managed block are preserved when
+you omit `--mount-root`.
+
+Generated/copied files are overwritten, so keep project-specific instructions
+outside them. Refreshing project files does not upgrade the installed package
+or update, restart, or save existing images. See [Hosts](docs/hosts.md) for
+the file ownership rules and [Images](docs/images.md) for image-side MCP updates.
+
 ## Requirements
 
 Node 22.12 or later.
@@ -26,6 +40,10 @@ The source projection currently supports macOS and needs
 
 ## What the agent gets
 
+Use `pharo-agent --help` for the command overview, or append `--help` to a
+command for its options, defaults, and an example: `pharo-agent init --help`
+or `pharo-agent image add --help`. Help works before project setup.
+
 Reference, for reading rather than typing: these are the commands the guidance
 hands to the agent.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@evref-bl/pharo-agent",
-  "version": "0.5.5",
+  "version": "0.6.0",
   "private": false,
   "description": "Terminal-first Pharo integration for coding agents.",
   "license": "Apache-2.0",
@@ -31,9 +31,9 @@
     "test": "node --test"
   },
   "dependencies": {
-    "@evref-bl/pharo-mcp": "2.1.1",
-    "@evref-bl/plexus": "0.5.5",
-    "@evref-bl/plexus-gateway": "0.5.5",
+    "@evref-bl/pharo-mcp": "2.2.0",
+    "@evref-bl/plexus": "0.5.6",
+    "@evref-bl/plexus-gateway": "0.5.6",
     "@modelcontextprotocol/sdk": "1.32.1"
   }
 }

package/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "pharo-agent",
-  "version": "0.5.5",
+  "version": "0.6.0",
   "description": "Terminal-first Pharo image setup for coding agents.",
   "author": {
     "name": "Evref-BL",

package/skills/pharo-setup/SKILL.md

@@ -1,14 +1,14 @@
 ---
 name: pharo-setup
-description: Enable Pharo image tooling in the current Pharo project.
+description: Enable or refresh Pharo image tooling in the current Pharo project.
 ---
 
-Run this only when the user asks to enable Pharo tooling in this project.
+Run this only when the user asks to enable or refresh Pharo tooling in this project.
 
 From the project root, run the released CLI that matches this plugin:
 
 ```sh
-npx --yes @evref-bl/pharo-agent@0.5.5 init --host claude
+npx --yes @evref-bl/pharo-agent@0.6.0 init --host claude
 ```
 
 Name the host this chat runs in: `--host claude` in Claude Code,
@@ -16,6 +16,13 @@ Name the host this chat runs in: `--host claude` in Claude Code,
 Do not configure an MCP server in the agent host. The command adds only a
 conditional instruction block, so Pharo guidance stays out of unrelated work.
 
+After upgrading the plugin/CLI, re-run the setup command from the project root
+with the same host to refresh the generated guide and copied skills/references.
+Those files are overwritten; keep project-specific guidance outside the host's
+managed block and outside generated/copied paths. Omit `--mount-root` to retain
+existing settings. Image declarations, runtime state, and live image code are
+preserved. This refresh does not install a newer package or upgrade image tools.
+
 Setup initializes the current directory, creating `plexus.json` with
 no image when it is absent. Register one before the first `pharo-agent open`:
 

package/src/cli.js

@@ -1,4 +1,5 @@
 import { hostChoices, hostList } from "./hosts.js";
+import { usage } from "./help.js";
 import { initialize } from "./init.js";
 import { addImage, listImages, removeImage, useImage } from "./images.js";
 import { callImageTool, listImageTools, serveImagesMcp } from "./gateway.js";
@@ -72,24 +73,6 @@ function takeImageOption(args) {
   return { image, rest: [...args.slice(0, index), ...args.slice(index + 2)] };
 }
 
-function usage() {
-  return [
-    "Usage:",
-    `  pharo-agent init --host <${hostChoices()}> [--mount-root <path>]`,
-    "  pharo-agent image list",
-    "  pharo-agent image templates",
-    "  pharo-agent image add <id> --template <name> [--category <name>] [--profile <id>]",
-    "  pharo-agent image use <id>",
-    "  pharo-agent image remove <id>",
-    "  pharo-agent open [--image <id>]",
-    "  pharo-agent status",
-    "  pharo-agent close [--image <id>]",
-    "  pharo-agent mcp [--image <id>]",
-    "  pharo-agent pharo list [--image <id>]",
-    "  pharo-agent pharo <tool> [arguments-json] [--image <id>]",
-  ].join("\n");
-}
-
 function requireNoArguments(command, args) {
   if (args.length > 0) {
     throw new Error(`${command} does not accept arguments`);
@@ -120,16 +103,16 @@ export function exitCodeForToolResult(result) {
 
 export async function main(args) {
   const [command, ...rest] = args;
-  if (command === "init") {
-    const result = initialize(parseInit(rest));
-    console.log(JSON.stringify({ ok: true, ...result }, null, 2));
-    return;
-  }
   // A caller reaching for help is asking the same question wherever the word
   // lands, and `image add --help` answering that it needs an image id is no
   // answer at all.
   if (!command || args.some((value) => value === "--help" || value === "help")) {
-    console.log(usage());
+    console.log(usage(args.filter((value) => value !== "--help" && value !== "help")));
+    return;
+  }
+  if (command === "init") {
+    const result = initialize(parseInit(rest));
+    console.log(JSON.stringify({ ok: true, ...result }, null, 2));
     return;
   }
   const projectRoot = findProjectRoot();

package/src/help.js

@@ -0,0 +1,92 @@
+import { hostChoices, hostIds } from "./hosts.js";
+
+const commands = {
+  init: {
+    usage: `init --host <${hostChoices()}> [--mount-root <path>]`,
+    description: "Initialize the current project for the required agent host. Write its managed instruction block,\n"
+      + "pharo.AGENTS.md, and workflow skills/references. Re-run to refresh those generated files.\n"
+      + "The mount root defaults to .pharo-agent/mounts; omit --mount-root to keep an existing setting.",
+    example: `init --host ${hostIds[0]}`,
+  },
+  "image list": {
+    usage: "image list",
+    description: "List the project's declared images, default image, and recorded open state.",
+    example: "image list",
+  },
+  "image templates": {
+    usage: "image templates",
+    description: "List available launcher templates and their categories. A name in several categories\n"
+      + "needs --category when passed to image add.",
+    example: "image templates",
+  },
+  "image add": {
+    usage: "image add <id> --template <name> [--category <name>] [--profile <id>]",
+    description: "Declare an image with a required id and template name; open creates it later.\n"
+      + "Use --category for an ambiguous template name and --profile to choose a launcher profile.\n"
+      + "The first declared image becomes the default.",
+    example: "image add dev --template '<template name>'",
+  },
+  "image use": {
+    usage: "image use <id>",
+    description: "Make the required declared image the project's default. It may already be open.",
+    example: "image use dev",
+  },
+  "image remove": {
+    usage: "image remove <id>",
+    description: "Remove the required image declaration. Close the image first. Its image files are kept.\n"
+      + "Removing the default image clears the default selection.",
+    example: "image remove dev",
+  },
+  open: {
+    usage: "open [--image <id>]",
+    description: "Create if needed and open an image with its tools and source projection. Omit --image\n"
+      + "to use the project's default image. Other open images stay open. Pharo versions outside\n"
+      + "the MCP support range open without tools or a source projection.",
+    example: "open --image dev",
+  },
+  status: {
+    usage: "status",
+    description: "Report all images this project has open. This command does not accept --image.",
+    example: "status",
+  },
+  close: {
+    usage: "close [--image <id>]",
+    description: "Close the selected image and its source projection. Omitting --image closes all images\n"
+      + "this project opened, rather than only the default image.",
+    example: "close --image dev",
+  },
+  mcp: {
+    usage: "mcp [--image <id>]",
+    description: "Expose an open image's tools as a command-scoped stdio MCP server. Omit --image\n"
+      + "to use the project's default image. The server exits with this command.",
+    example: "mcp --image dev",
+  },
+  "pharo list": {
+    usage: "pharo list [--image <id>]",
+    description: "List an open image's advertised tools. Omit --image to use the project's default image.\n"
+      + "Use tool_search and tool_get to discover and inspect the rest of its catalogue.",
+    example: "pharo list",
+  },
+  pharo: {
+    usage: "pharo <tool> [arguments-json] [--image <id>]",
+    description: "Call a tool in an open image. Arguments must be a JSON object and default to {}.\n"
+      + "Omit --image to use the project's default image. Inspect the tool's schema with tool_get\n"
+      + "before calling it; a failed tool result makes the command exit unsuccessfully.",
+    example: 'pharo tool_get \'{"name":"class_search"}\'',
+  },
+};
+
+export function usage(args = []) {
+  const key = ["image", "pharo"].includes(args[0]) && args[1]
+    ? `${args[0]} ${args[1]}`
+    : args[0];
+  const command = Object.hasOwn(commands, key) ? commands[key]
+    : Object.hasOwn(commands, args[0]) ? commands[args[0]] : undefined;
+  if (command) {
+    return `Usage:\n  pharo-agent ${command.usage}\n\n${command.description}\n\nExample:\n  pharo-agent ${command.example}`;
+  }
+  const entries = Object.entries(commands)
+    .filter(([name]) => args[0] !== "image" || name.startsWith("image "));
+  return ["Usage:", ...entries.map(([, entry]) => `  pharo-agent ${entry.usage}`),
+    "", "Use pharo-agent <command> --help for options and examples."].join("\n");
+}

package/src/init.js

@@ -76,6 +76,13 @@ function pharoGuide() {
 
 ${generatedBy}. Edits here are replaced the next time it runs.
 
+After upgrading the plugin/CLI, re-run \`pharo-agent init --host <host>\` from
+the project root with the same host to refresh this guide and the copied skills
+and references. Omit \`--mount-root\` to keep existing settings. Image declarations,
+runtime state, and live code are preserved. Keep project-specific instructions
+outside generated/copied files and outside the host guide's managed block.
+Refreshing project files does not install a newer package or upgrade image tools.
+
 \`plexus.json\` declares this project's images. A freshly initialized
 project declares none; register one before the first \`pharo-agent open\`: