@evref-bl/pharo-agent 0.11.0 → 0.12.1

package/.claude-plugin/plugin.json

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

package/.mcp.json

@@ -1,8 +1,12 @@
 {
   "mcpServers": {
     "image": {
-      "command": "node",
-      "args": ["${CLAUDE_PLUGIN_ROOT}/bin/pharo-agent.js", "mcp"]
+      "command": "npx",
+      "args": [
+        "--yes",
+        "@evref-bl/pharo-agent@0.12.1",
+        "mcp"
+      ]
     }
   }
 }

package/README.md

@@ -6,6 +6,20 @@ Claude Code, Codex and OpenCode.
 
 ## Setup
 
+In Claude Code, install it as a plugin:
+
+```text
+/plugin marketplace add Evref-BL/pharo-agent-plugin
+/plugin install pharo-agent@evref-bl
+```
+
+Then ask the agent to enable Pharo tooling in a project. The plugin carries a
+setup skill that runs the command below for you, and declares the `image` MCP
+server, so the running image's tools reach the chat without a server
+configured by hand. [Hosts](docs/hosts.md) covers enabling it per project
+rather than everywhere.
+
+Any host can run the CLI instead, which is the whole of the setup either way.
 In the project directory:
 
 ```sh
@@ -35,8 +49,10 @@ the file ownership rules and [Images](docs/images.md) for image-side MCP updates
 
 Node 22.12 or later.
 
-The source projection currently supports macOS and needs
-[fuse-t](https://www.fuse-t.org/). Its daemon is downloaded for you.
+Images and their Pharo tools run anywhere Node does. The source projection is
+the exception: it needs macOS with [fuse-t](https://www.fuse-t.org/), whose
+daemon is downloaded for you. Everywhere else an image starts with its tools
+and says that the projection is not available, rather than failing.
 
 ## What the agent gets
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@evref-bl/pharo-agent",
-  "version": "0.11.0",
+  "version": "0.12.1",
   "private": false,
   "description": "Terminal-first Pharo integration for coding agents.",
   "license": "Apache-2.0",
@@ -33,7 +33,7 @@
   },
   "dependencies": {
     "@evref-bl/pharo-mcp": "3.3.1",
-    "@evref-bl/plexus": "0.11.0",
+    "@evref-bl/plexus": "0.12.1",
     "@modelcontextprotocol/sdk": "1.32.1"
   },
   "devDependencies": {

package/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "pharo-agent",
-  "version": "0.11.0",
+  "version": "0.12.1",
   "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 or refresh Pharo tooling in this proj
 From the project root, run the released CLI that matches this plugin:
 
 ```sh
-npx --yes @evref-bl/pharo-agent@0.11.0 init --host claude
+npx --yes @evref-bl/pharo-agent@0.12.1 init --host claude
 ```
 
 Name the host this chat runs in: `--host claude` in Claude Code,

package/src/cli.js

@@ -29,11 +29,18 @@ function parseInit(args) {
   return { host, mountRoot };
 }
 
+/**
+ * The template is required, and the loop below refuses the call without one,
+ * which the dynamic key assignment hides from the typechecker.
+ *
+ * @returns {{ id: string, template: string, category?: string, profile?: string }}
+ */
 function parseImageAdd(args) {
   const [id, ...rest] = args;
   if (!id || id.startsWith("--")) {
     throw new Error("image add requires an image id");
   }
+  /** @type {{ id: string, template?: string, category?: string, profile?: string }} */
   const parsed = { id };
   const options = {
     "--template": "template",
@@ -56,7 +63,7 @@ function parseImageAdd(args) {
   if (!parsed.template) {
     throw new Error("image add requires --template <name>");
   }
-  return parsed;
+  return { ...parsed, template: parsed.template };
 }
 
 // `image start` and `image stop` name their subject, like `image use` and

package/src/gateway.js

@@ -1,7 +1,7 @@
 import { createRequire } from "node:module";
 import { PlexusGateway } from "@evref-bl/plexus/gateway";
+import { loadProjectState } from "@evref-bl/plexus";
 import {
-  readJson,
   selectRunningImage,
   unappliedPharoMcpPin,
 } from "./runtime.js";
@@ -15,7 +15,10 @@ export const { version } = createRequire(import.meta.url)("../package.json");
 // is nothing to register here and nothing that can go stale between the call
 // that started the image and this one.
 export function imageGateway(projectRoot, running) {
-  const state = readJson(running.statePath);
+  const state = loadProjectState(running.statePath);
+  if (!state) {
+    throw new Error(`PLexus has no state at ${running.statePath}.`);
+  }
   const { image, mcpServerId } = selectRunningImage(state, running.imageId);
   if (image.id !== running.imageId || mcpServerId !== running.mcpServerId) {
     throw new Error(`The PLexus image ${running.imageId} changed; run pharo-agent image start again.`);

package/src/help.js

@@ -40,15 +40,16 @@ const commands = {
   },
   "image start": {
     usage: "image start [<id>]",
-    description: "Create if needed and start an image with its tools and source projection. Omit the id\n"
-      + "to use the project's default image. Images already running stay running. Pharo versions\n"
-      + "outside the MCP support range start without tools or a source projection.",
+    description: "Create if needed and start an image with its Pharo tools. Omit the id to use the\n"
+      + "project's default image. Images already running stay running. A source projection is\n"
+      + "mounted on macOS with fuse-t; elsewhere the image starts without one and says so.\n"
+      + "Pharo versions outside the MCP support range start without tools or a projection.",
     example: "image start dev",
   },
   "image stop": {
     usage: "image stop [<id>] [--all]",
-    description: "Stop the named image and its source projection, or the project's default image when\n"
-      + "no id is given. Use --all to stop every image this project started.",
+    description: "Stop the named image and any source projection it has, or the project's default\n"
+      + "image when no id is given. Use --all to stop every image this project started.",
     example: "image stop dev",
   },
   mcp: {

package/src/images.js

@@ -1,9 +1,5 @@
-import {
-  configuredImages,
-  projectIdentity,
-  readProjectConfig,
-  writeProjectConfig,
-} from "./project.js";
+import { declareProjectImage, removeProjectImage } from "@evref-bl/plexus";
+import { configuredImages } from "./project.js";
 import { defaultImageId, readConfig, readRunningImages, writeConfig } from "./runtime.js";
 
 export const defaultLoadScript = "pharo/load-mcp.st";
@@ -16,11 +12,6 @@ function assertNotRunning(projectRoot, imageId, action) {
   }
 }
 
-function derivedImageName(projectRoot, imageId) {
-  const { name } = projectIdentity(projectRoot);
-  return `${name}-{workspaceId}-${imageId}`;
-}
-
 export function listImages(projectRoot) {
   const configured = configuredImages(projectRoot);
   const running = readRunningImages(projectRoot);
@@ -51,40 +42,37 @@ export function listImages(projectRoot) {
   };
 }
 
-/** @param {{ id: string, template?: string, category?: string, profile?: string }} request */
+/**
+ * PLexus owns `plexus.json`, so PLexus writes it. This package chooses what
+ * to declare — the load script that puts the pinned MCP in the image — and
+ * leaves the schema, the name template, the defaults and the validation to
+ * the package that reads them back.
+ *
+ * @param {{ id: string, template: string, category?: string, profile?: string }} request
+ */
 export function addImage(projectRoot, request) {
   const { id, template, category, profile } = request;
-  const config = readProjectConfig(projectRoot);
-  const images = Array.isArray(config.images) ? config.images : [];
-  if (images.some((image) => image.id === id)) {
-    throw new Error(`Image ${id} is already configured.`);
-  }
-  const imageName = derivedImageName(projectRoot, id);
-  if (images.some((image) => image.imageName === imageName)) {
-    throw new Error(`Image name ${imageName} is already configured.`);
+  const declaredBefore = configuredImages(projectRoot).length;
+  const config = declareProjectImage(projectRoot, {
+    id,
+    templateName: template,
+    ...(category ? { templateCategory: category } : {}),
+    ...(profile ? { profileId: profile } : {}),
+    loadScript: defaultLoadScript,
+  });
+  const declared = config.images.find((image) => image.id === id);
+  if (!declared) {
+    throw new Error(`PLexus declared image ${id} but did not record it.`);
   }
 
-  const image = {
-    id,
-    imageName,
-    mcp: { loadScript: defaultLoadScript, loadPolicy: "ifMissing" },
-    create: {
-      kind: "template",
-      ...(profile ? { profileId: profile } : {}),
-      templateName: template,
-      ...(category ? { templateCategory: category } : {}),
-      cleanupPolicy: "workspace_cleanup_only",
-    },
-  };
-  writeProjectConfig(projectRoot, { ...config, images: [...images, image] });
   const pluginConfig = readConfig(projectRoot);
-  const isDefault = pluginConfig.defaultImage === undefined && images.length === 0;
+  const isDefault = pluginConfig.defaultImage === undefined && declaredBefore === 0;
   if (isDefault) {
     writeConfig(projectRoot, { ...pluginConfig, defaultImage: id });
   }
   return {
     id,
-    imageName,
+    imageName: declared.imageName,
     isDefault,
     templateName: template,
     ...(category ? { templateCategory: category } : {}),
@@ -100,16 +88,11 @@ export function useImage(projectRoot, id) {
 }
 
 export function removeImage(projectRoot, id) {
-  const config = readProjectConfig(projectRoot);
-  const images = Array.isArray(config.images) ? config.images : [];
-  if (!images.some((image) => image.id === id)) {
+  if (!configuredImages(projectRoot).some((image) => image.id === id)) {
     throw new Error(`Image ${id} is not configured.`);
   }
   assertNotRunning(projectRoot, id, "removing it");
-  writeProjectConfig(projectRoot, {
-    ...config,
-    images: images.filter((image) => image.id !== id),
-  });
+  removeProjectImage(projectRoot, id);
   const pluginConfig = readConfig(projectRoot);
   if (pluginConfig.defaultImage === id) {
     const { defaultImage: _removed, ...rest } = pluginConfig;

package/src/init.js

@@ -137,8 +137,10 @@ starts without MCP tools or a source projection, saying so.
 use <id>\` changes the default, and \`pharo-agent image remove <id>\` drops a
 declaration. Stop an image before removing its declaration.
 
-Use \`pharo-agent image start\` before live-image work and edit projected source
-under \`.pharo-agent/mounts\`.
+Use \`pharo-agent image start\` before live-image work. On macOS with fuse-t
+installed the image's source is also projected under \`.pharo-agent/mounts\`
+and can be edited as files; everywhere else the Pharo tools are the way in,
+and \`image start\` says so.
 
 With the pharo-agent plugin enabled for this project, the image's tools are MCP
 tools: start an image with \`image_start\` and call the rest by name. Without it,

package/src/live.js

@@ -9,7 +9,7 @@ import {
   stopProjectImage,
 } from "@evref-bl/plexus";
 import { callImageTool } from "./gateway.js";
-import { readProjectConfig, writeProjectConfig } from "./project.js";
+import { readProjectConfig } from "./project.js";
 import {
   readConfig,
   readRunningImages,
@@ -24,6 +24,48 @@ import {
 
 export const pifsRelease = "v0.9.2";
 
+// fuse-t ships as a macOS installer package, so it lands in /usr/local
+// whatever Homebrew's prefix is. The unversioned symlink is what the daemon
+// links against.
+export const fuseLibraryPath = "/usr/local/lib/libfuse-t.dylib";
+
+/**
+ * Whether a source projection can be mounted here.
+ *
+ * PIFS needs macOS and fuse-t, which is a kernel-adjacent install the user
+ * has to approve. PLexus and the Pharo MCP run anywhere, so until this was
+ * checked, `image start` mounted unconditionally and then stopped the image
+ * when the mount failed -- every image on Linux and Windows, and on any Mac
+ * without fuse-t. The image and its tools were never the part that could not
+ * work.
+ *
+ * @param {{ platform?: string, exists?: (path: string) => boolean }} [host]
+ */
+export function projectionAvailability(host = {}) {
+  const platform = host.platform ?? process.platform;
+  const exists = host.exists ?? fs.existsSync;
+  if (platform !== "darwin") {
+    return {
+      available: false,
+      reason: "A source projection needs macOS and fuse-t, which this platform"
+        + ` (${platform}) cannot provide.`,
+    };
+  }
+  if (!exists(fuseLibraryPath)) {
+    return {
+      available: false,
+      reason: "A source projection needs fuse-t, which is not installed."
+        + " Install it with `brew install --cask fuse-t`.",
+    };
+  }
+  return { available: true };
+}
+
+export function projectionUnavailableWarning(imageId, reason) {
+  return `${reason} Image ${imageId} is running with its Pharo tools and no`
+    + " source projection; read and edit its code through the tools.";
+}
+
 // The class-side PIFSServer messages this plugin sends into the image. The
 // release automation checks that a published PIFS still implements them: a pin
 // bump that leaves a removed selector in place passes every test here, because
@@ -106,48 +148,6 @@ export function imageCreationPlan(listed, imageId) {
   return "none";
 }
 
-// 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 [
@@ -207,12 +207,14 @@ export async function startAgentImage(projectRoot, imageId) {
     writeRunningImages(projectRoot, runningImages);
     restarted = true;
   }
-  fetchPifsRelease(pifsCloneDirectory(projectRoot));
+  if (projectionAvailability().available) {
+    fetchPifsRelease(pifsCloneDirectory(projectRoot));
+  }
   const launcher = new ScopedPharoLauncher({ projectRoot });
   const plan = imageCreationPlan(await launcher.listImages(), resolved);
   const created = plan !== "none";
   if (created) {
-    await resolveTemplateCategory(projectRoot, launcher, resolved);
+    // PLexus resolves which category the template lives in.
     await launcher.createImage(resolved);
   }
   const started = await runLifecycle(
@@ -237,6 +239,24 @@ export async function startAgentImage(projectRoot, imageId) {
     writeRunningImages(projectRoot, { ...runningImages, [resolved]: record });
     return { ...record, created, warning: pharoMcpWarning(withoutMcp) };
   }
+  const unappliedPin = unappliedPharoMcpPin(image);
+  const projection = projectionAvailability();
+  if (!projection.available) {
+    // The image and its tools are the point; the projection is the extra this
+    // package bundles where the platform allows it.
+    const record = { statePath: started.statePath, imageId: image.id, mcpServerId };
+    writeRunningImages(projectRoot, { ...runningImages, [resolved]: record });
+    return {
+      imageId: image.id,
+      created,
+      ...(restarted ? { restarted } : {}),
+      warning: [
+        projectionUnavailableWarning(image.id, projection.reason),
+        unappliedPin,
+      ].filter(Boolean).join("\n"),
+    };
+  }
+
   const mountPath = resolveMountPath(projectRoot, readConfig(projectRoot), image.id);
   fs.mkdirSync(path.dirname(mountPath), { recursive: true });
   const record = {
@@ -255,7 +275,6 @@ export async function startAgentImage(projectRoot, imageId) {
     throw error;
   }
   writeRunningImages(projectRoot, { ...runningImages, [resolved]: { ...record, projectionPort } });
-  const unappliedPin = unappliedPharoMcpPin(image);
   return {
     imageId: image.id,
     created,

package/src/mcpServer.js

@@ -39,8 +39,9 @@ const lifecycleTools = [
     name: "image_start",
     description:
       "Start one of this project's Pharo images, creating it from its template "
-      + "when it does not exist yet, and mount its source projection. The "
-      + "image's own tools are listed once it answers.",
+      + "when it does not exist yet. The image's own tools are listed once it "
+      + "answers. On macOS with fuse-t its source also mounts as files; "
+      + "elsewhere the image starts without that and says so.",
     inputSchema: {
       type: "object",
       properties: {
@@ -61,7 +62,7 @@ const lifecycleTools = [
   {
     name: "image_stop",
     description:
-      "Stop a running image and the source projection this project started for it.",
+      "Stop a running image, and any source projection this project started for it.",
     inputSchema: {
       type: "object",
       properties: {

package/src/project.js

@@ -1,7 +1,16 @@
 import fs from "node:fs";
 import path from "node:path";
+// The config file is PLexus's, so its name and its path come from PLexus.
+// Spelling them here made this package a second definition of another
+// package's format, free to drift from it without anything noticing.
+import {
+  createProjectConfigFile,
+  loadProjectConfig,
+  plexusProjectConfigFileName,
+  projectConfigPath as plexusProjectConfigPath,
+} from "@evref-bl/plexus";
 
-export const projectConfigFileName = "plexus.json";
+export const projectConfigFileName = plexusProjectConfigFileName;
 
 function projectRootAbove(start) {
   let directory = path.resolve(start);
@@ -47,43 +56,26 @@ export function enclosingProjectRoot(start) {
 }
 
 export function projectConfigPath(projectRoot) {
-  return path.join(projectRoot, projectConfigFileName);
+  return plexusProjectConfigPath(projectRoot);
 }
 
 export function pluginDirectory(projectRoot) {
   return path.join(projectRoot, ".pharo-agent");
 }
 
-export function projectIdentity(projectRoot) {
-  const name = path.basename(path.resolve(projectRoot));
-  const id = name
-    .replaceAll(/[^A-Za-z0-9._-]+/g, "-")
-    .replaceAll(/^-+|-+$/g, "")
-    .toLowerCase();
-  return { id: id || "pharo-project", name };
-}
-
+// Validated, not merely parsed: a malformed plexus.json then fails naming
+// what is wrong with it, rather than reaching PLexus as a shape it refuses
+// further in.
 export function readProjectConfig(projectRoot) {
-  const configPath = projectConfigPath(projectRoot);
-  try {
-    return JSON.parse(fs.readFileSync(configPath, "utf8"));
-  } catch (error) {
-    throw new Error(`Cannot read ${configPath}: ${error.message}`);
-  }
-}
-
-export function writeProjectConfig(projectRoot, config) {
-  fs.writeFileSync(projectConfigPath(projectRoot), `${JSON.stringify(config, null, 2)}\n`);
+  return loadProjectConfig(projectRoot);
 }
 
 export function createProjectConfig(projectRoot) {
-  const { id, name } = projectIdentity(projectRoot);
-  const config = { id, name, images: [] };
-  writeProjectConfig(projectRoot, config);
-  return config;
+  return createProjectConfigFile(projectRoot, {
+    name: path.basename(path.resolve(projectRoot)),
+  });
 }
 
 export function configuredImages(projectRoot) {
-  const config = readProjectConfig(projectRoot);
-  return Array.isArray(config.images) ? config.images : [];
+  return readProjectConfig(projectRoot).images;
 }

package/src/runtime.js

@@ -1,5 +1,6 @@
 import fs from "node:fs";
 import path from "node:path";
+import { loadProjectState } from "@evref-bl/plexus";
 import { configuredImages, pluginDirectory } from "./project.js";
 
 export function runtimeDirectory(projectRoot) {
@@ -114,13 +115,10 @@ export function imageProcessIsAlive(pid) {
 }
 
 export function recordedImageIsRunning(record) {
-  let state;
-  try {
-    state = readJson(record.statePath);
-  } catch {
-    return false;
-  }
-  const image = (state.images ?? []).find((candidate) => candidate.id === record.imageId);
+  // PLexus owns the state file, so PLexus reads it: a hand-rolled JSON.parse
+  // here was this package deciding what another package's format means.
+  const state = loadProjectState(record.statePath);
+  const image = state?.images.find((candidate) => candidate.id === record.imageId);
   return image?.status === "running" && imageProcessIsAlive(image.pid);
 }