@haemmid/pi-processes 0.9.0 → 0.9.2

package/CHANGELOG.md

@@ -4,6 +4,36 @@ 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
+
+- `output`, `logs`, and `kill` accept either `id` or `name` as process selector.
+- `start` and `restart` return suggested next commands with `name="..."`.
+- Shared `resolveSelector` utility for consistent validation across actions.
+
+### Changed
+
+- Ambiguous name resolution now uses simpler error messages.
+- Tool description updated to mention id/name duality.
+
+### Fixed
+
+- `kill` test: message assertion updated for new ambiguous error format.
+
 ## [0.9.0] - 2026-07-01
 
 Initial public release of `@haemmid/pi-processes`.

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,25 +171,31 @@ 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
-process output id="backend-dev"
+process output id="proc_1"
+process output name="backend-dev"
 process logs id="proc_1"
+process logs name="backend-dev"
 process kill id="backend-dev"
-process kill id="proc_1" force=true
+process kill name="backend-dev" force=true
 process clear
 ```
 
 ### Field rules
 
-- `start`/`restart` require `command` and `name`.
-- `output`, `logs`, and `kill` require `id`.
+- `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.0",
+  "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/actions/kill.ts

@@ -1,66 +1,36 @@
 import type { ExecuteResult } from "../../constants";
 import type { ProcessManager } from "../../manager";
 import { sanitizeLine } from "../../utils";
+import { resolveSelector } from "./utils";
 
 interface KillParams {
   id?: string;
+  name?: string;
   force?: boolean;
 }
 
-function notFoundResult(id: string): ExecuteResult {
-  const message = `Process not found: ${id}`;
-  return {
-    content: [{ type: "text", text: message }],
-    details: {
-      action: "kill",
-      success: false,
-      message,
-    },
-  };
-}
-
-function ambiguousResult(
-  id: string,
-  matches: Array<{ id: string; name: string }>,
-): ExecuteResult {
-  const choices = matches
-    .map((match) => `${match.id} ("${sanitizeLine(match.name)}")`)
-    .join(", ");
-  const message =
-    `Process name is ambiguous: ${id}. ` +
-    `Use an exact process ID instead. Matches: ${choices}`;
-  return {
-    content: [{ type: "text", text: message }],
-    details: {
-      action: "kill",
-      success: false,
-      message,
-    },
-  };
-}
-
 export async function executeKill(
   params: KillParams,
   manager: ProcessManager,
 ): Promise<ExecuteResult> {
-  if (!params.id) {
+  const error = resolveSelector(params, manager);
+  if (error) {
+    return { ...error, details: { ...error.details, action: "kill" } };
+  }
+
+  const query = params.id || params.name || "";
+  const resolved = manager.resolve(query);
+  if (!resolved.ok) {
     return {
-      content: [{ type: "text", text: "Missing required parameter: id" }],
+      content: [{ type: "text", text: `Process not found: "${query}"` }],
       details: {
         action: "kill",
         success: false,
-        message: "Missing required parameter: id",
+        message: `Process not found: "${query}"`,
       },
     };
   }
 
-  const resolved = manager.resolve(params.id);
-  if (!resolved.ok) {
-    return resolved.reason === "ambiguous"
-      ? ambiguousResult(params.id, resolved.matches ?? [])
-      : notFoundResult(params.id);
-  }
-
   const proc = resolved.info;
   const force = params.force ?? false;
   const signal = force ? "SIGKILL" : "SIGTERM";

package/src/tools/actions/logs.ts

@@ -1,52 +1,31 @@
 import type { ExecuteResult } from "../../constants";
 import type { ProcessManager } from "../../manager";
 import { sanitizeLine } from "../../utils";
+import { resolveSelector } from "./utils";
 
 interface LogsParams {
   id?: string;
+  name?: string;
 }
 
 export function executeLogs(
   params: LogsParams,
   manager: ProcessManager,
 ): ExecuteResult {
-  if (!params.id) {
-    return {
-      content: [{ type: "text", text: "Missing required parameter: id" }],
-      details: {
-        action: "logs",
-        success: false,
-        message: "Missing required parameter: id",
-      },
-    };
+  const error = resolveSelector(params, manager);
+  if (error) {
+    return { ...error, details: { ...error.details, action: "logs" } };
   }
 
-  const resolved = manager.resolve(params.id);
+  const query = params.id || params.name || "";
+  const resolved = manager.resolve(query);
   if (!resolved.ok) {
-    if (resolved.reason === "ambiguous") {
-      const choices = (resolved.matches ?? [])
-        .map((match) => `${match.id} ("${sanitizeLine(match.name)}")`)
-        .join(", ");
-      const message =
-        `Process name is ambiguous: ${params.id}. ` +
-        `Use an exact process ID instead. Matches: ${choices}`;
-      return {
-        content: [{ type: "text", text: message }],
-        details: {
-          action: "logs",
-          success: false,
-          message,
-        },
-      };
-    }
-
-    const message = `Process not found: ${params.id}`;
     return {
-      content: [{ type: "text", text: message }],
+      content: [{ type: "text", text: `Process not found: "${query}"` }],
       details: {
         action: "logs",
         success: false,
-        message,
+        message: `Process not found: "${query}"`,
       },
     };
   }

package/src/tools/actions/output.ts

@@ -1,73 +1,39 @@
 import { configLoader } from "../../config";
-import {
-  type ExecuteResult,
-  LIVE_STATUSES,
-  type ResolveProcessResult,
-} from "../../constants";
+import { type ExecuteResult, LIVE_STATUSES } from "../../constants";
 import type { ProcessManager } from "../../manager";
 import { formatStatus, sanitizeLine } from "../../utils";
+import { resolveSelector } from "./utils";
 
 const MAX_BYTES = 50 * 1024; // 50KB
 
 interface OutputParams {
   id?: string;
-}
-
-function resolveProcessResult(
-  result: ResolveProcessResult,
-  action: "output" | "logs",
-  id: string,
-): ExecuteResult | null {
-  if (result.ok) return null;
-
-  if (result.reason === "ambiguous") {
-    const choices = (result.matches ?? [])
-      .map((match) => `${match.id} ("${sanitizeLine(match.name)}")`)
-      .join(", ");
-    const message =
-      `Process name is ambiguous: ${id}. ` +
-      `Use an exact process ID instead. Matches: ${choices}`;
-    return {
-      content: [{ type: "text", text: message }],
-      details: {
-        action,
-        success: false,
-        message,
-      },
-    };
-  }
-
-  const message = `Process not found: ${id}`;
-  return {
-    content: [{ type: "text", text: message }],
-    details: {
-      action,
-      success: false,
-      message,
-    },
-  };
+  name?: string;
 }
 
 export function executeOutput(
   params: OutputParams,
   manager: ProcessManager,
 ): ExecuteResult {
-  if (!params.id) {
+  const error = resolveSelector(params, manager);
+  if (error) {
+    return { ...error, details: { ...error.details, action: "output" } };
+  }
+
+  const query = params.id || params.name || "";
+  const resolved = manager.resolve(query);
+  if (!resolved.ok) {
+    // Should not reach here, but guard anyway
     return {
-      content: [{ type: "text", text: "Missing required parameter: id" }],
+      content: [{ type: "text", text: `Process not found: "${query}"` }],
       details: {
         action: "output",
         success: false,
-        message: "Missing required parameter: id",
+        message: `Process not found: "${query}"`,
       },
     };
   }
 
-  const resolved = manager.resolve(params.id);
-  if (!resolved.ok) {
-    return resolveProcessResult(resolved, "output", params.id) as ExecuteResult;
-  }
-
   const proc = resolved.info;
   const { defaultTailLines } = configLoader.getConfig().output;
   const output = manager.getOutput(proc.id, defaultTailLines);

package/src/tools/actions/restart.ts

@@ -3,6 +3,7 @@ import type { ExecuteResult } from "../../constants";
 import type { ProcessManager } from "../../manager";
 import { formatTimestamp, sanitizeLine } from "../../utils";
 import { executeKill } from "./kill";
+import { buildNextCommands } from "./utils";
 
 interface RestartParams {
   name?: string;
@@ -100,7 +101,12 @@ export async function executeRestart(
   }
 
   const startedAt = formatTimestamp(proc.startTime);
-  const message = `Restarted "${sanitizeLine(proc.name)}" (${proc.id}, PID: ${proc.pid})\nStarted at: ${startedAt}\nLogs: ${proc.stdoutFile}`;
+  const message = [
+    `Restarted "${sanitizeLine(proc.name)}" (${proc.id}, PID: ${proc.pid})`,
+    `Started at: ${startedAt}`,
+    `Logs: ${proc.stdoutFile}`,
+    buildNextCommands(proc.name),
+  ].join("\n");
   return {
     content: [{ type: "text", text: message }],
     details: {

package/src/tools/actions/start.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 { formatTimestamp, sanitizeLine } from "../../utils";
+import { buildNextCommands } from "./utils";
 
 interface StartParams {
   name?: string;
@@ -59,7 +60,12 @@ export function executeStart(
     }
 
     const startedAt = formatTimestamp(proc.startTime);
-    const message = `Started "${sanitizeLine(proc.name)}" (${proc.id}, PID: ${proc.pid})\nStarted at: ${startedAt}\nLogs: ${proc.stdoutFile}`;
+    const message = [
+      `Started "${sanitizeLine(proc.name)}" (${proc.id}, PID: ${proc.pid})`,
+      `Started at: ${startedAt}`,
+      `Logs: ${proc.stdoutFile}`,
+      buildNextCommands(proc.name),
+    ].join("\n");
     return {
       content: [{ type: "text", text: message }],
       details: {

package/src/tools/actions/utils.ts

@@ -0,0 +1,104 @@
+import type { ExecuteResult } from "../../constants";
+import type { ProcessManager } from "../../manager";
+import { sanitizeLine } from "../../utils";
+
+interface SelectorParams {
+  id?: string;
+  name?: string;
+}
+
+export interface ResolvedProcess {
+  id: string;
+  name: string;
+}
+
+export function resolveSelector(
+  params: SelectorParams,
+  manager: ProcessManager,
+): ExecuteResult | null {
+  // Missing selector
+  if (!params.id && !params.name) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: 'Missing process selector. Use either id="proc_1" or name="backend-dev".',
+        },
+      ],
+      details: {
+        action: "output",
+        success: false,
+        message: "Missing process selector. Use either id or name.",
+      },
+    };
+  }
+
+  // Both specified
+  if (params.id && params.name) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: "Use either id or name, not both.",
+        },
+      ],
+      details: {
+        action: "output",
+        success: false,
+        message: "Use either id or name, not both.",
+      },
+    };
+  }
+
+  // Resolve by id or name
+  const query = params.id || params.name || "";
+  const resolved = manager.resolve(query);
+
+  if (resolved.ok) {
+    return null; // resolved successfully
+  }
+
+  if (resolved.reason === "ambiguous") {
+    const choices = (resolved.matches ?? [])
+      .map((match) => `${match.id} ("${sanitizeLine(match.name)}")`)
+      .join(", ");
+    return {
+      content: [
+        {
+          type: "text",
+          text: `Process name is ambiguous: "${query}". Use an exact process ID instead. Matches: ${choices}`,
+        },
+      ],
+      details: {
+        action: "output",
+        success: false,
+        message: `Process name is ambiguous: "${query}". Matches: ${choices}`,
+      },
+    };
+  }
+
+  return {
+    content: [
+      {
+        type: "text",
+        text: `Process not found: "${query}"`,
+      },
+    ],
+    details: {
+      action: "output",
+      success: false,
+      message: `Process not found: "${query}"`,
+    },
+  };
+}
+
+export function buildNextCommands(name: string): string {
+  return [
+    "",
+    "Next commands:",
+    `  process output name="${name}"`,
+    `  process logs name="${name}"`,
+    `  process restart "<command>" name="${name}"`,
+    `  process kill name="${name}"`,
+  ].join("\n");
+}

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(
@@ -26,7 +27,7 @@ const ProcessesParams = Type.Object({
   name: Type.Optional(
     Type.String({
       description:
-        "Friendly name for the process (required for start/restart, e.g. 'backend-dev', 'test-runner')",
+        "Friendly name for the process (required for start/restart; accepted for output/logs/kill as alternative to id)",
     }),
   ),
   cwd: Type.Optional(
@@ -38,7 +39,7 @@ const ProcessesParams = Type.Object({
   id: Type.Optional(
     Type.String({
       description:
-        "Exact process ID or exact friendly name to match (required for output/kill/logs).",
+        "Exact process ID (e.g. 'proc_1') or process name (for output/logs/kill as alternative to name)",
     }),
   ),
   force: Type.Optional(
@@ -55,12 +56,16 @@ 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
-- output/logs/kill require 'id' (exact process ID or exact friendly name)
+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
 
+Processes have both an exact process id (e.g. proc_1) and a stable name (e.g. astro-dev).
+For output/logs/kill, prefer name="..." when referring to a named dev server.
+
 Processes continue in the background. Use process output or process logs for a one-off snapshot when you need to inspect status. Do not poll repeatedly just to wait.
 Tool-triggered kills never notify.`,
     promptSnippet:
@@ -71,6 +76,7 @@ Tool-triggered kills never notify.`,
       "Use process output or process logs only for a one-off inspection, explicit user request, or debugging.",
       "Use process restart to replace an existing process — it safely awaits kill before starting the new one.",
       "Do not poll process output/list repeatedly just to wait for a process to finish.",
+      'For output/logs/kill, prefer name="..." when referring to a named dev server.',
     ],
 
     parameters: ProcessesParams,

package/src/utils/ansi.ts

@@ -41,7 +41,7 @@ export function stripAnsi(str: string): string {
   }
 
   // Strip terminal control chars like carriage return/backspace that can
-  // corrupt TUI layout when rendered back into pi.
+  // corrupt output formatting.
   return Array.from(clean)
     .filter((char) => {
       const code = char.codePointAt(0) ?? 0;
@@ -55,12 +55,11 @@ export function stripAnsi(str: string): string {
 }
 
 /**
- * Sanitize process output for single-line TUI rendering.
+ * Sanitize process output for single-line display.
  *
- * This is stricter than stripAnsi(): after terminal escapes are removed, any
- * remaining control bytes (carriage returns, backspaces, BEL, embedded
- * newlines, etc.) are dropped so process output cannot move the cursor or
- * alter Pi's surrounding TUI.
+ * After terminal escapes are removed, any remaining control bytes
+ * (carriage returns, backspaces, BEL, embedded newlines, etc.) are dropped
+ * so process output is safe for agent display.
  */
 export function sanitizeLine(str: string): string {
   return stripAnsi(str).replace(/\t/g, "  ");