@evref-bl/pharo-agent 0.1.0 → 0.2.1

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "pharo-agent",
   "displayName": "Pharo Agent",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Terminal-first Pharo image setup for coding agents.",
   "author": {
     "name": "Evref-BL",
@@ -10,5 +10,9 @@
   "homepage": "https://github.com/Evref-BL/pharo-agent-plugin",
   "repository": "https://github.com/Evref-BL/pharo-agent-plugin",
   "license": "Apache-2.0",
-  "keywords": ["pharo", "smalltalk", "mcp"]
+  "keywords": [
+    "pharo",
+    "smalltalk",
+    "mcp"
+  ]
 }

package/README.md

@@ -4,8 +4,7 @@
 OpenCode. It has one small setup skill; a project receives the full Pharo
 guidance only after setup.
 
-The project must already contain a `plexus.project.json` that declares one
-agent-facing image. Initialize it for one selected agent host:
+Initialize the current directory for one selected agent host:
 
 ```sh
 npx --yes @evref-bl/pharo-agent init --host codex
@@ -15,6 +14,22 @@ It writes a small conditional instruction block, `pharo.AGENTS.md`, and copies
 on-demand Pharo workflow skills and references from the pinned MCP template
 package. It does not install an agent-host MCP server.
 
+`init` acts on the current directory and never searches above it. If that
+directory has no `plexus.project.json`, it creates one that declares the
+project and no image; an existing one is left untouched. It refuses to run
+inside an enclosing PLexus project rather than initializing that project root.
+
+Register the image the project needs before the first `open`:
+
+```sh
+pharo-agent image add dev --template 'Pharo 13.0 - 64bit (stable)'
+```
+
+`image add` registers a template-created image with the pinned MCP load policy
+and makes it active when no other image is. `image list`, `image use <id>`,
+and `image remove <id>` cover the rest; an open image must be closed before
+its declaration changes.
+
 `open` starts the project image through PLexus, loads PIFS, and mounts its
 projection below `.pharo-agent/mounts`. `close` unmounts the projection and
 closes the PLexus image. `pharo` calls any exposed MCP tool through the same

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@evref-bl/pharo-agent",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "private": false,
   "description": "Terminal-first Pharo integration for coding agents.",
   "license": "Apache-2.0",
@@ -32,8 +32,8 @@
   },
   "dependencies": {
     "@evref-bl/pharo-mcp": "1.4.1",
-    "@evref-bl/plexus": "0.2.1",
-    "@evref-bl/plexus-gateway": "0.2.1",
+    "@evref-bl/plexus": "0.3.0",
+    "@evref-bl/plexus-gateway": "0.3.0",
     "@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.1.0",
+  "version": "0.2.1",
   "description": "Terminal-first Pharo image setup for coding agents.",
   "author": {
     "name": "Evref-BL",
@@ -10,7 +10,11 @@
   "homepage": "https://github.com/Evref-BL/pharo-agent-plugin",
   "repository": "https://github.com/Evref-BL/pharo-agent-plugin",
   "license": "Apache-2.0",
-  "keywords": ["pharo", "smalltalk", "mcp"],
+  "keywords": [
+    "pharo",
+    "smalltalk",
+    "mcp"
+  ],
   "extensions": {
     "com.openai": {
       "requires_local_executor": true,

package/skills/pharo-setup/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: pharo-setup
-description: Enable Pharo image tooling in the current PLexus project.
+description: Enable Pharo image tooling in the current Pharo project.
 ---
 
 Run this only when the user asks to enable Pharo tooling in this project.
@@ -8,12 +8,20 @@ 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.1.0 init --host codex
+npx --yes @evref-bl/pharo-agent@0.2.1 init --host codex
 ```
 
 Use `--host claude` in Claude Code and `--host opencode` in OpenCode.
 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.
 
+Setup initializes the current directory, creating `plexus.project.json` with
+no image when it is absent. Register one before the first `pharo-agent open`:
+
+```sh
+pharo-agent image list
+pharo-agent image add dev --template '<launcher template name>'
+```
+
 After setup, read `pharo.AGENTS.md` in this chat before doing Pharo work. A
 new chat picks up the conditional project guidance automatically.

package/src/cli.js

@@ -1,4 +1,5 @@
 import { initialize } from "./init.js";
+import { addImage, listImages, removeImage, useImage } from "./images.js";
 import { callActiveTool, listActiveTools, serveActiveMcp } from "./gateway.js";
 import { closeAgentImage, openAgentImage } from "./live.js";
 import { findProjectRoot } from "./project.js";
@@ -25,10 +26,40 @@ function parseInit(args) {
   return { host, mountRoot };
 }
 
+function parseImageAdd(args) {
+  const [id, ...rest] = args;
+  if (!id || id.startsWith("--")) {
+    throw new Error("image add requires an image id");
+  }
+  const parsed = { id };
+  const options = { "--template": "template", "--category": "category", "--profile": "profile" };
+  for (let index = 0; index < rest.length; index += 1) {
+    const option = rest[index];
+    const key = options[option];
+    if (!key) {
+      throw new Error(`Unknown image add option: ${option}`);
+    }
+    const value = rest[index + 1];
+    if (!value) {
+      throw new Error(`${option} requires a value`);
+    }
+    parsed[key] = value;
+    index += 1;
+  }
+  if (!parsed.template) {
+    throw new Error("image add requires --template <name>");
+  }
+  return parsed;
+}
+
 function usage() {
   return [
     "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 use <id>",
+    "  pharo-agent image remove <id>",
     "  pharo-agent open",
     "  pharo-agent status",
     "  pharo-agent close",
@@ -70,6 +101,28 @@ export async function main(args) {
     return;
   }
   const projectRoot = findProjectRoot();
+  if (command === "image") {
+    const [subcommand, ...imageArgs] = rest;
+    if (subcommand === "list") {
+      requireNoArguments("image list", imageArgs);
+      console.log(JSON.stringify({ ok: true, ...listImages(projectRoot) }, null, 2));
+      return;
+    }
+    if (subcommand === "add") {
+      console.log(JSON.stringify({ ok: true, ...addImage(projectRoot, parseImageAdd(imageArgs)) }, null, 2));
+      return;
+    }
+    if (subcommand === "use" || subcommand === "remove") {
+      const [id, ...extra] = imageArgs;
+      if (!id || extra.length > 0) {
+        throw new Error(`image ${subcommand} requires one image id`);
+      }
+      const result = subcommand === "use" ? useImage(projectRoot, id) : removeImage(projectRoot, id);
+      console.log(JSON.stringify({ ok: true, ...result }, null, 2));
+      return;
+    }
+    throw new Error(`Unsupported image command: ${subcommand ?? ""}\n${usage()}`);
+  }
   if (command === "open") {
     requireNoArguments(command, rest);
     console.log(JSON.stringify({ ok: true, ...(await openAgentImage(projectRoot)) }, null, 2));

package/src/images.js

@@ -0,0 +1,95 @@
+import fs from "node:fs";
+import {
+  configuredImages,
+  projectIdentity,
+  readProjectConfig,
+  writeProjectConfig,
+} from "./project.js";
+import { activePath, readActive } from "./runtime.js";
+
+export const defaultLoadScript = "pharo/load-mcp.st";
+
+function assertNoOpenImage(projectRoot, imageId, action) {
+  if (!fs.existsSync(activePath(projectRoot))) return;
+  const active = readActive(projectRoot);
+  if (active.imageId === imageId) {
+    throw new Error(`Image ${imageId} is open. Run pharo-agent close before ${action}.`);
+  }
+}
+
+function derivedImageName(projectRoot, imageId) {
+  const { name } = projectIdentity(projectRoot);
+  return `${name}-{workspaceId}-${imageId}`;
+}
+
+export function listImages(projectRoot) {
+  return {
+    images: configuredImages(projectRoot).map((image) => ({
+      id: image.id,
+      imageName: image.imageName,
+      active: image.active === true,
+      templateName: image.create?.templateName,
+      templateCategory: image.create?.templateCategory,
+    })),
+  };
+}
+
+export function addImage(projectRoot, { id, template, category, profile }) {
+  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 image = {
+    id,
+    imageName,
+    active: !images.some((other) => other.active === true),
+    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] });
+  return { id, imageName, active: image.active, templateName: template };
+}
+
+export function useImage(projectRoot, id) {
+  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 not configured.`);
+  }
+  for (const image of images) {
+    if (image.active === true && image.id !== id) {
+      assertNoOpenImage(projectRoot, image.id, "switching the active image");
+    }
+  }
+  writeProjectConfig(projectRoot, {
+    ...config,
+    images: images.map((image) => ({ ...image, active: image.id === id })),
+  });
+  return { activeImageId: 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)) {
+    throw new Error(`Image ${id} is not configured.`);
+  }
+  assertNoOpenImage(projectRoot, id, "removing it");
+  writeProjectConfig(projectRoot, {
+    ...config,
+    images: images.filter((image) => image.id !== id),
+  });
+  return { removedImageId: id };
+}

package/src/init.js

@@ -1,7 +1,13 @@
 import fs from "node:fs";
 import path from "node:path";
 import { templateDirectory as mcpTemplateDirectory } from "@evref-bl/pharo-mcp";
-import { findProjectRoot, pluginDirectory } from "./project.js";
+import {
+  createProjectConfig,
+  enclosingProjectRoot,
+  pluginDirectory,
+  projectConfigFileName,
+  projectConfigPath,
+} from "./project.js";
 
 const managedStart = "<!-- pharo-agent:begin -->";
 const managedEnd = "<!-- pharo-agent:end -->";
@@ -71,6 +77,18 @@ function guidance() {
 function pharoGuide() {
   return `# Pharo project guide
 
+\`plexus.project.json\` declares this project's images. A freshly initialized
+project declares none; register one before the first \`pharo-agent open\`:
+
+\`\`\`sh
+pharo-agent image list
+pharo-agent image add dev --template '<launcher template name>'
+\`\`\`
+
+\`image add\` makes the first registered image active. \`pharo-agent image use
+<id>\` switches the active image, and \`pharo-agent image remove <id>\` drops a
+declaration. Close an image before changing its declaration.
+
 Use \`pharo-agent open\` before live-image work and edit projected source under
 \`.pharo-agent/mounts\`. Use \`pharo-agent pharo list\` to inspect the complete
 live MCP tool surface and \`pharo-agent pharo <tool> [arguments-json]\` to call
@@ -108,18 +126,38 @@ Image, Tonel, Iceberg, disk Git, and host processes are separate states.
 `;
 }
 
+function resolveInitProjectRoot(cwd) {
+  const projectRoot = path.resolve(cwd);
+  if (fs.existsSync(projectConfigPath(projectRoot))) {
+    return { projectRoot, createdProjectConfig: false };
+  }
+
+  const enclosing = enclosingProjectRoot(projectRoot);
+  if (enclosing) {
+    throw new Error(
+      `${projectRoot} is inside the PLexus project at ${enclosing}. `
+        + `Initialize that project root, or remove its ${projectConfigFileName}.`,
+    );
+  }
+
+  return { projectRoot, createdProjectConfig: true };
+}
+
 export function initialize({ host, mountRoot, cwd = process.cwd() }) {
   const guideName = hostGuide[host];
   if (!guideName) {
     throw new Error("--host must be codex, claude, or opencode");
   }
 
-  const projectRoot = findProjectRoot(cwd);
+  const { projectRoot, createdProjectConfig } = resolveInitProjectRoot(cwd);
   const directory = pluginDirectory(projectRoot);
   const configPath = path.join(directory, "config.json");
   const pharoGuidePath = path.join(projectRoot, "pharo.AGENTS.md");
   assertGeneratedGuideCanBeUpdated(pharoGuidePath);
   assertManagedBlockCanBeUpdated(path.join(projectRoot, guideName));
+  if (createdProjectConfig) {
+    createProjectConfig(projectRoot);
+  }
   fs.mkdirSync(directory, { recursive: true });
   if (!fs.existsSync(configPath) || mountRoot !== undefined) {
     fs.writeFileSync(
@@ -134,5 +172,5 @@ export function initialize({ host, mountRoot, cwd = process.cwd() }) {
   copyDirectory(path.join(templates, "pharo-skills"), path.join(directory, "skills"));
   updateManagedBlock(path.join(projectRoot, guideName), guidance());
 
-  return { projectRoot, guideName };
+  return { projectRoot, guideName, createdProjectConfig };
 }

package/src/project.js

@@ -1,11 +1,13 @@
 import fs from "node:fs";
 import path from "node:path";
 
+export const projectConfigFileName = "plexus.project.json";
+
 export function findProjectRoot(start = process.cwd()) {
   let directory = path.resolve(start);
 
   while (true) {
-    if (fs.existsSync(path.join(directory, "plexus.project.json"))) {
+    if (fs.existsSync(path.join(directory, projectConfigFileName))) {
       return directory;
     }
 
@@ -17,19 +19,66 @@ export function findProjectRoot(start = process.cwd()) {
   }
 }
 
+export function enclosingProjectRoot(start) {
+  const directory = path.resolve(start);
+  const parent = path.dirname(directory);
+  if (parent === directory) return undefined;
+  try {
+    return findProjectRoot(parent);
+  } catch {
+    return undefined;
+  }
+}
+
+export function projectConfigPath(projectRoot) {
+  return path.join(projectRoot, projectConfigFileName);
+}
+
 export function pluginDirectory(projectRoot) {
   return path.join(projectRoot, ".pharo-agent");
 }
 
-export function configuredActiveImageId(projectRoot) {
-  const configPath = path.join(projectRoot, "plexus.project.json");
-  let config;
+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 };
+}
+
+export function readProjectConfig(projectRoot) {
+  const configPath = projectConfigPath(projectRoot);
   try {
-    config = JSON.parse(fs.readFileSync(configPath, "utf8"));
+    return JSON.parse(fs.readFileSync(configPath, "utf8"));
   } catch (error) {
     throw new Error(`Cannot read ${configPath}: ${error.message}`);
   }
-  const images = Array.isArray(config.images) ? config.images.filter((image) => image?.active) : [];
+}
+
+export function writeProjectConfig(projectRoot, config) {
+  fs.writeFileSync(projectConfigPath(projectRoot), `${JSON.stringify(config, null, 2)}\n`);
+}
+
+export function createProjectConfig(projectRoot) {
+  const { id, name } = projectIdentity(projectRoot);
+  const config = { id, name, images: [] };
+  writeProjectConfig(projectRoot, config);
+  return config;
+}
+
+export function configuredImages(projectRoot) {
+  const config = readProjectConfig(projectRoot);
+  return Array.isArray(config.images) ? config.images : [];
+}
+
+export function configuredActiveImageId(projectRoot) {
+  const images = configuredImages(projectRoot).filter((image) => image?.active);
+  if (images.length === 0) {
+    throw new Error(
+      "No active image in plexus.project.json. Register one with pharo-agent image add <id> --template <name>.",
+    );
+  }
   if (images.length !== 1 || typeof images[0].id !== "string") {
     throw new Error(
       `pharo-agent needs exactly one active image in plexus.project.json; found ${images.length}.`,