@haemmid/pi-processes 0.9.1 → 0.9.2

package/CHANGELOG.md

@@ -4,6 +4,19 @@ All notable changes to this project will be documented in this file.
 
 This project follows semantic versioning for public releases.
 
+## [0.9.2] - 2026-07-02
+
+### Added
+
+- `ensure` action for idempotent dev-server workflows.
+- `ensure` reuses existing process when name+command+cwd match.
+- `ensure` returns conflict error when name matches but configuration differs.
+- `ensure` returns next commands (output/logs/restart/kill by name).
+
+### Changed
+
+- Version bumped to 0.9.2.
+
 ## [0.9.1] - 2026-07-02
 
 ### Added

package/README.md

@@ -94,7 +94,7 @@ For Astro/Vite dev servers, ask the agent:
 
 ```text
 Use the process tool for the Astro dev server.
-Start `npm run dev -- --host 0.0.0.0` as `my-site:astro`.
+Ensure `npm run dev -- --host 0.0.0.0` is running as `my-site:astro`.
 Use `process output` when you need logs.
 Do not restart after ordinary .astro, .ts, or .css edits.
 Restart only after package/config/env changes or if the server exits.
@@ -104,10 +104,10 @@ Typical tool flow:
 
 ```text
 process list
-process start "npm run dev -- --host 0.0.0.0" name="my-site:astro"
-process output id="my-site:astro"
+process ensure "npm run dev -- --host 0.0.0.0" name="my-site:astro"
+process output name="my-site:astro"
 process restart "npm run dev -- --host 0.0.0.0" name="my-site:astro"
-process kill id="my-site:astro"
+process kill name="my-site:astro"
 ```
 
 ## Demo
@@ -156,7 +156,8 @@ The tool is named `process`.
 
 | Action | Description |
 |--------|-------------|
-| `start` | Start a managed process. |
+| `start` | Start a managed process (refuses if a live process with the same name exists). |
+| `ensure` | Idempotent start: reuse existing process if name+command+cwd match, start new otherwise. |
 | `restart` | Kill existing process and start a new one (safe: await kill → start). |
 | `list` | List managed processes. |
 | `output` | Return a one-off tailed stdout/stderr snapshot. |
@@ -170,6 +171,8 @@ The tool is named `process`.
 process start "pnpm dev" name="backend-dev"
 process start "pnpm test --watch" name="tests"
 process start "pnpm dev" name="backend-dev" cwd="/path/to/project"
+process ensure "pnpm dev" name="backend-dev"
+process ensure "pnpm dev" name="backend-dev" cwd="/path/to/project"
 process restart "pnpm dev" name="backend-dev"
 process restart "pnpm dev" name="backend-dev" force=true
 process list
@@ -184,13 +187,14 @@ process clear
 
 ### Field rules
 
-- `start`/`restart` require `command` and `name`.
+- `start`/`ensure`/`restart` require `command` and `name`.
 - `output`, `logs`, and `kill` accept either `id` (exact process ID) or `name` (process name).
 - `kill` accepts `force=true` to send `SIGKILL` instead of `SIGTERM`.
-- `start` refuses if a process with the same name is already running.
+- `start` refuses if a live process with the same name is already running.
+- `ensure` reuses existing process when name+command+cwd match; returns conflict error otherwise.
 - `restart` safely kills the existing process (awaited) before starting a new one.
 - `restart` accepts `force=true` to send `SIGKILL` instead of `SIGTERM`.
-- `start`/`restart` accept `cwd` to override the working directory (defaults to session cwd).
+- `start`/`ensure`/`restart` accept `cwd` to override the working directory (defaults to session cwd).
 - `output`, `logs`, and `kill` return an error if both `id` and `name` are provided.
 
 ## Killing processes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@haemmid/pi-processes",
-  "version": "0.9.1",
+  "version": "0.9.2",
   "description": "Agent-facing background process manager for Pi and pi-web automation workflows.",
   "license": "MIT",
   "type": "module",

package/src/manager.ts

@@ -235,6 +235,34 @@ export class ProcessManager {
     return this.toProcessInfo(managed);
   }
 
+  /**
+   * Ensure a process is running with the given name, command, and cwd.
+   *
+   * - If a live process with the same name + cwd exists → return it.
+   * - If a live process with the same name exists but different cwd/command →
+   *   return null (conflict).
+   * - If no live process with this name exists → start a new one.
+   * - Finished processes with the same name are ignored.
+   */
+  ensure(name: string, command: string, cwd: string): ProcessInfo | null {
+    // Find live process with this name
+    const liveMatch = Array.from(this.processes.values()).find(
+      (proc) => proc.name === name && LIVE_STATUSES.has(proc.status),
+    );
+
+    if (liveMatch) {
+      // Same name, same cwd → reuse
+      if (liveMatch.cwd === cwd && liveMatch.command === command) {
+        return this.toProcessInfo(liveMatch);
+      }
+      // Same name, different cwd/command → conflict
+      return null;
+    }
+
+    // No live match → start new
+    return this.start(name, command, cwd);
+  }
+
   list(): ProcessInfo[] {
     return Array.from(this.processes.values())
       .map((p) => this.toProcessInfo(p))

package/src/tools/actions/ensure.ts

@@ -0,0 +1,87 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { ExecuteResult } from "../../constants";
+import type { ProcessManager } from "../../manager";
+import { formatTimestamp, sanitizeLine } from "../../utils";
+import { buildNextCommands } from "./utils";
+
+interface EnsureParams {
+  name?: string;
+  command?: string;
+  cwd?: string;
+}
+
+export function executeEnsure(
+  params: EnsureParams,
+  manager: ProcessManager,
+  ctx: ExtensionContext,
+): ExecuteResult {
+  if (!params.name) {
+    return {
+      content: [{ type: "text", text: "Missing required parameter: name" }],
+      details: {
+        action: "ensure",
+        success: false,
+        message: "Missing required parameter: name",
+      },
+    };
+  }
+  if (!params.command) {
+    return {
+      content: [{ type: "text", text: "Missing required parameter: command" }],
+      details: {
+        action: "ensure",
+        success: false,
+        message: "Missing required parameter: command",
+      },
+    };
+  }
+
+  const proc = manager.ensure(
+    params.name,
+    params.command,
+    params.cwd ?? ctx.cwd,
+  );
+
+  if (proc === null) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: `A process named "${params.name}" is already running with a different command or cwd. Use process kill first, or process restart to replace it.`,
+        },
+      ],
+      details: {
+        action: "ensure",
+        success: false,
+        message: `A process named "${params.name}" is already running with a different configuration.`,
+      },
+    };
+  }
+
+  const startedAt = formatTimestamp(proc.startTime);
+
+  // Check if this was an existing process or newly started
+  const isNew = proc.pid > 0;
+  const message = isNew
+    ? [
+        `Started "${sanitizeLine(proc.name)}" (${proc.id}, PID: ${proc.pid})`,
+        `Started at: ${startedAt}`,
+        `Logs: ${proc.stdoutFile}`,
+        buildNextCommands(proc.name),
+      ].join("\n")
+    : [
+        `Already running "${sanitizeLine(proc.name)}" (${proc.id}, PID: ${proc.pid})`,
+        `Reusing existing managed process.`,
+        buildNextCommands(proc.name),
+      ].join("\n");
+
+  return {
+    content: [{ type: "text", text: message }],
+    details: {
+      action: "ensure",
+      success: true,
+      message,
+      process: proc,
+    },
+  };
+}

package/src/tools/actions/index.ts

@@ -2,6 +2,7 @@ import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type { ExecuteResult } from "../../constants";
 import type { ProcessManager } from "../../manager";
 import { executeClear } from "./clear";
+import { executeEnsure } from "./ensure";
 import { executeKill } from "./kill";
 import { executeList } from "./list";
 import { executeLogs } from "./logs";
@@ -26,6 +27,8 @@ export async function executeAction(
   switch (params.action) {
     case "start":
       return executeStart(params, manager, ctx);
+    case "ensure":
+      return executeEnsure(params, manager, ctx);
     case "restart":
       return executeRestart(params, manager, ctx);
     case "list":

package/src/tools/index.ts

@@ -8,6 +8,7 @@ const ProcessesParams = Type.Object({
   action: Type.Union(
     [
       Type.Literal("start"),
+      Type.Literal("ensure"),
       Type.Literal("list"),
       Type.Literal("output"),
       Type.Literal("logs"),
@@ -17,7 +18,7 @@ const ProcessesParams = Type.Object({
     ],
     {
       description:
-        "Action: start (run command), list (show all), output (get recent output), logs (get log file paths), kill (terminate or force-kill), clear (remove finished), restart (kill existing and start new)",
+        "Action: start (run command), ensure (idempotent start), list (show all), output (get recent output), logs (get log file paths), kill (terminate or force-kill), clear (remove finished), restart (kill existing and start new)",
     },
   ),
   command: Type.Optional(
@@ -55,8 +56,9 @@ export function setupProcessesTools(pi: ExtensionAPI, manager: ProcessManager) {
     label: "Process",
     description: `Manage background processes.
 
-Actions: start, list, output, logs, kill, clear, restart.
-- start/restart require 'name' and 'command' — restart kills existing process first
+Actions: start, ensure, list, output, logs, kill, clear, restart.
+- start/restart/ensure require 'name' and 'command'
+- ensure is an idempotent start: reuses existing process if name+command+cwd match
 - output/logs/kill accept either 'id' (exact process ID) or 'name' (process name)
 - kill supports optional 'force=true' for SIGKILL
 - restart is preferred over start+kill: it safely awaits kill before starting new process