@evref-bl/pharo-agent 0.10.2 → 0.12.0

package/src/project.js

@@ -1,9 +1,18 @@
 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;
 
-export function findProjectRoot(start = process.cwd()) {
+function projectRootAbove(start) {
   let directory = path.resolve(start);
 
   while (true) {
@@ -13,12 +22,28 @@ export function findProjectRoot(start = process.cwd()) {
 
     const parent = path.dirname(directory);
     if (parent === directory) {
-      throw new Error("No plexus.json found above the current directory");
+      return undefined;
     }
     directory = parent;
   }
 }
 
+export function findProjectRoot(start = process.cwd()) {
+  const found = projectRootAbove(start);
+  if (found) return found;
+
+  // A plugin's MCP server is started by the host, in the plugin's own
+  // directory rather than the project's, so the working directory leads
+  // nowhere. The host says where the project is, and that is only consulted
+  // here, after the ordinary search has failed, so running the CLI inside a
+  // project still answers with that project.
+  const hosted = process.env.CLAUDE_PROJECT_DIR;
+  const hostedRoot = hosted ? projectRootAbove(hosted) : undefined;
+  if (hostedRoot) return hostedRoot;
+
+  throw new Error("No plexus.json found above the current directory");
+}
+
 export function enclosingProjectRoot(start) {
   const directory = path.resolve(start);
   const parent = path.dirname(directory);
@@ -31,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,13 +1,14 @@
 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) {
   return path.join(pluginDirectory(projectRoot), "runtime");
 }
 
-export function activePath(projectRoot) {
-  return path.join(runtimeDirectory(projectRoot), "active.json");
+export function runningImagesPath(projectRoot) {
+  return path.join(runtimeDirectory(projectRoot), "running.json");
 }
 
 export function readJson(filePath) {
@@ -30,23 +31,22 @@ export function writeConfig(projectRoot, config) {
   fs.writeFileSync(configPath(projectRoot), `${JSON.stringify(config, null, 2)}\n`);
 }
 
-export function readOpenImages(projectRoot) {
-  const filePath = activePath(projectRoot);
+export function readRunningImages(projectRoot) {
+  const filePath = runningImagesPath(projectRoot);
   if (!fs.existsSync(filePath)) return {};
   const recorded = readJson(filePath);
-  if (recorded && typeof recorded.images === "object" && recorded.images !== null) {
-    return recorded.images;
-  }
-  return typeof recorded?.imageId === "string" ? { [recorded.imageId]: recorded } : {};
+  return recorded && typeof recorded.images === "object" && recorded.images !== null
+    ? recorded.images
+    : {};
 }
 
-export function writeOpenImages(projectRoot, images) {
+export function writeRunningImages(projectRoot, images) {
   if (Object.keys(images).length === 0) {
-    fs.rmSync(activePath(projectRoot), { force: true });
+    fs.rmSync(runningImagesPath(projectRoot), { force: true });
     return;
   }
   fs.mkdirSync(runtimeDirectory(projectRoot), { recursive: true });
-  fs.writeFileSync(activePath(projectRoot), `${JSON.stringify({ images }, null, 2)}\n`);
+  fs.writeFileSync(runningImagesPath(projectRoot), `${JSON.stringify({ images }, null, 2)}\n`);
 }
 
 export function defaultImageId(projectRoot) {
@@ -70,7 +70,7 @@ export function defaultImageId(projectRoot) {
   }
   throw new Error(
     `Several images are configured (${images.map((image) => image.id).join(", ")}); `
-      + "choose one with pharo-agent image use <id>, or pass --image <id>.",
+      + "choose one with pharo-agent image use <id>, or name one.",
   );
 }
 
@@ -82,26 +82,26 @@ export function resolveImageId(projectRoot, imageId) {
   return imageId;
 }
 
-export function readOpenImage(projectRoot, imageId) {
+export function readRunningImage(projectRoot, imageId) {
   const resolved = resolveImageId(projectRoot, imageId);
-  const open = readOpenImages(projectRoot)[resolved];
-  if (!open) {
+  const running = readRunningImages(projectRoot)[resolved];
+  if (!running) {
     throw new Error(
-      `Image ${resolved} is not open. Run pharo-agent open${imageId ? ` --image ${resolved}` : ""} first.`,
+      `Image ${resolved} is not running. Run pharo-agent image start ${resolved} first.`,
     );
   }
-  if (open.mcp === false) {
+  if (running.mcp === false) {
     throw new Error(
-      `Image ${resolved} is open without MCP, so it offers no Pharo tools. `
+      `Image ${resolved} is running without MCP, so it offers no Pharo tools. `
         + "Register an image on a Pharo version the MCP contract supports to use them.",
     );
   }
-  return open;
+  return running;
 }
 
-// A record in the project's runtime state says this project opened the image,
+// A record in the project's runtime state says this project started the image,
 // not that the image is still there. PLexus reclaims a dead image's port and
-// relaunches on the next open, so the only thing standing between a crashed
+// relaunches on the next start, so the only thing standing between a crashed
 // image and a working one is believing the record.
 export function imageProcessIsAlive(pid) {
   if (!Number.isInteger(pid) || pid <= 0) return false;
@@ -114,14 +114,11 @@ export function imageProcessIsAlive(pid) {
   }
 }
 
-export function openedImageIsAlive(open) {
-  let state;
-  try {
-    state = readJson(open.statePath);
-  } catch {
-    return false;
-  }
-  const image = (state.images ?? []).find((candidate) => candidate.id === open.imageId);
+export function recordedImageIsRunning(record) {
+  // 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);
 }
 
@@ -164,7 +161,7 @@ export function selectRunningImage(state, imageId) {
 // written against. PLexus records it; this says it.
 export function unappliedPharoMcpPin(image) {
   if (image?.pharoMcpLoad?.state !== "provided") return undefined;
-  return `Image ${image.id} opened with the Pharo MCP it already had, so the version this project pins`
+  return `Image ${image.id} started with the Pharo MCP it already had, so the version this project pins`
     + " was not loaded and its tools may differ from the ones this project expects."
     + " Recreate the image, or set mcp.loadPolicy to always.";
 }