@evref-bl/pharo-agent 0.3.7 → 0.3.8

package/.claude-plugin/plugin.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@evref-bl/pharo-agent",
-  "version": "0.3.7",
+  "version": "0.3.8",
   "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": "1.5.0",
-    "@evref-bl/plexus": "0.4.5",
-    "@evref-bl/plexus-gateway": "0.4.5",
+    "@evref-bl/pharo-mcp": "1.5.1",
+    "@evref-bl/plexus": "0.4.7",
+    "@evref-bl/plexus-gateway": "0.4.7",
     "@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.3.7",
+  "version": "0.3.8",
   "description": "Terminal-first Pharo image setup for coding agents.",
   "author": {
     "name": "Evref-BL",

package/skills/pharo-setup/SKILL.md

@@ -8,7 +8,7 @@ Run this only when the user asks to enable 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.3.7 init --host codex
+npx --yes @evref-bl/pharo-agent@0.3.8 init --host codex
 ```
 
 Use `--host claude` in Claude Code and `--host opencode` in OpenCode.

package/src/cli.js

@@ -32,7 +32,7 @@ function parseImageAdd(args) {
     throw new Error("image add requires an image id");
   }
   const parsed = { id };
-  const options = { "--template": "template", "--category": "category", "--profile": "profile" };
+  const options = { "--template": "template", "--profile": "profile" };
   for (let index = 0; index < rest.length; index += 1) {
     const option = rest[index];
     const key = options[option];
@@ -67,7 +67,7 @@ function usage() {
     "Usage:",
     "  pharo-agent init --host <codex|claude|opencode> [--mount-root <path>]",
     "  pharo-agent image list",
-    "  pharo-agent image add <id> --template <name> [--category <name>] [--profile <id>]",
+    "  pharo-agent image add <id> --template <name> [--profile <id>]",
     "  pharo-agent image use <id>",
     "  pharo-agent image remove <id>",
     "  pharo-agent open [--image <id>]",

package/src/images.js

@@ -37,7 +37,7 @@ export function listImages(projectRoot) {
   };
 }
 
-export function addImage(projectRoot, { id, template, category, profile }) {
+export function addImage(projectRoot, { id, template, profile }) {
   const config = readProjectConfig(projectRoot);
   const images = Array.isArray(config.images) ? config.images : [];
   if (images.some((image) => image.id === id)) {
@@ -57,7 +57,6 @@ export function addImage(projectRoot, { id, template, category, profile }) {
       kind: "template",
       ...(profile ? { profileId: profile } : {}),
       templateName: template,
-      ...(category ? { templateCategory: category } : {}),
       cleanupPolicy: "workspace_cleanup_only",
     },
   };

package/src/live.js

@@ -9,7 +9,7 @@ import {
   resolvePlexusHomePath,
 } from "@evref-bl/plexus";
 import { callImageTool } from "./gateway.js";
-import { readProjectConfig } from "./project.js";
+import { readProjectConfig, writeProjectConfig } from "./project.js";
 import {
   defaultImageId,
   readConfig,
@@ -62,6 +62,48 @@ export function needsImageCreation(listed, imageId) {
   return summary.status === "declared";
 }
 
+// The launcher resolves a template name against its default group only, so an
+// image naming a template from any other group cannot be created until the
+// project config says which group that is. Find it once, on first creation.
+export async function resolveTemplateCategory(projectRoot, launcher, imageId) {
+  const config = readProjectConfig(projectRoot);
+  const images = Array.isArray(config.images) ? config.images : [];
+  const configured = images.find((image) => image.id === imageId);
+  const create = configured?.create;
+  if (!create?.templateName || create.templateCategory) {
+    return create?.templateCategory;
+  }
+
+  const listed = await launcher.listTemplates();
+  const templates = Array.isArray(listed?.templates) ? listed.templates : [];
+  const categories = [
+    ...new Set(
+      templates
+        .filter((template) => template?.name === create.templateName)
+        .map((template) => template?.templateCategory)
+        .filter(Boolean),
+    ),
+  ];
+  if (categories.length === 0) {
+    throw new Error(`No template named ${create.templateName} in any category.`);
+  }
+  if (categories.length > 1) {
+    throw new Error(
+      `Template ${create.templateName} exists in several categories: ${categories.join(", ")}.`
+      + ` Set create.templateCategory for image ${imageId} to choose one.`,
+    );
+  }
+
+  const [templateCategory] = categories;
+  writeProjectConfig(projectRoot, {
+    ...config,
+    images: images.map((image) => (image.id === imageId
+      ? { ...image, create: { ...image.create, templateCategory } }
+      : image)),
+  });
+  return templateCategory;
+}
+
 export function describeLifecycleFailure(failure) {
   const stderr = failure.launcherResult?.raw?.stderr?.trim();
   return [
@@ -116,13 +158,22 @@ export async function openAgentImage(projectRoot, imageId) {
   const launcher = new ScopedPharoLauncher({ projectRoot });
   const created = needsImageCreation(launcher.listImages(), resolved);
   if (created) {
+    await resolveTemplateCategory(projectRoot, launcher, resolved);
     await launcher.createImage(resolved);
   }
   const opened = await runLifecycle(
     () => openProject({ projectRoot, imageIds: [resolved] }),
     `PLexus could not open image ${resolved}.`,
   );
-  const { image, mcpServerId } = selectRunningImage(opened.state, resolved);
+  let image;
+  let mcpServerId;
+  try {
+    ({ image, mcpServerId } = selectRunningImage(opened.state, resolved));
+  } catch (error) {
+    // The image is running but unusable to us, so do not leave it behind.
+    await closeProject({ projectRoot, imageIds: [resolved] }).catch(() => {});
+    throw error;
+  }
   const mountPath = resolveMountPath(projectRoot, readConfig(projectRoot), image.id);
   fs.mkdirSync(path.dirname(mountPath), { recursive: true });
   const open = {

package/src/runtime.js

@@ -112,8 +112,14 @@ export function selectRunningImage(state, imageId) {
   }
   const image = images[0];
   if (!Array.isArray(image.mcpServers) || image.mcpServers.length !== 1) {
+    // PLexus withholds the route when the image is outside the MCP contract,
+    // and records why. Say that rather than only the endpoint count.
+    const contract = image.pharoMcpContract;
+    const reason = contract?.status === "unsupported" && contract.reason
+      ? ` ${contract.reason}`
+      : "";
     throw new Error(
-      `Image ${image.id} needs exactly one MCP endpoint; PLexus reported ${image.mcpServers?.length ?? 0}.`,
+      `Image ${image.id} needs exactly one MCP endpoint; PLexus reported ${image.mcpServers?.length ?? 0}.${reason}`,
     );
   }
   return { image, mcpServerId: image.mcpServers[0].id };