forge-openclaw-plugin 0.2.10 → 0.2.11

package/README.md

@@ -202,6 +202,14 @@ The skill is entity-format-driven. It teaches the agent how to:
 
 For local use, set the plugin origin to `http://127.0.0.1` or `http://localhost` and the plugin will bring Forge up on the configured port automatically.
 
+If you want to stop that plugin-managed local runtime cleanly, use:
+
+```bash
+forge stop
+```
+
+This only stops the runtime when it was auto-started by the OpenClaw plugin. If Forge was started manually some other way, `forge stop` tells you that instead of killing unrelated processes.
+
 ## Publishing and listing
 
 The reliable publication path for the Forge plugin is:

package/dist/openclaw/local-runtime.d.ts

@@ -1,3 +1,11 @@
 import type { ForgePluginConfig } from "./api-client.js";
+export type ForgeRuntimeStopResult = {
+    ok: boolean;
+    stopped: boolean;
+    managed: boolean;
+    message: string;
+    pid: number | null;
+};
 export declare function ensureForgeRuntimeReady(config: ForgePluginConfig): Promise<void>;
 export declare function primeForgeRuntime(config: ForgePluginConfig): void;
+export declare function stopForgeRuntime(config: ForgePluginConfig): Promise<ForgeRuntimeStopResult>;

package/dist/openclaw/local-runtime.js

@@ -1,6 +1,8 @@
 import { spawn } from "node:child_process";
 import { existsSync } from "node:fs";
+import { homedir } from "node:os";
 import path from "node:path";
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
 import { fileURLToPath } from "node:url";
 const LOCAL_HOSTNAMES = new Set(["127.0.0.1", "localhost", "::1"]);
 const STARTUP_TIMEOUT_MS = 15_000;
@@ -12,6 +14,63 @@ let startupPromise = null;
 function runtimeKey(config) {
     return `${config.origin}:${config.port}`;
 }
+function getRuntimeStatePath(config) {
+    const origin = new URL(config.origin).hostname.toLowerCase().replace(/[^a-z0-9._-]+/g, "-");
+    return path.join(homedir(), ".openclaw", "run", "forge-openclaw-plugin", `${origin}-${config.port}.json`);
+}
+async function writeRuntimeState(config, pid) {
+    const statePath = getRuntimeStatePath(config);
+    await mkdir(path.dirname(statePath), { recursive: true });
+    const payload = {
+        pid,
+        origin: config.origin,
+        port: config.port,
+        baseUrl: config.baseUrl,
+        startedAt: new Date().toISOString()
+    };
+    await writeFile(statePath, `${JSON.stringify(payload, null, 2)}\n`, "utf8");
+}
+async function clearRuntimeState(config) {
+    await rm(getRuntimeStatePath(config), { force: true });
+}
+async function readRuntimeState(config) {
+    try {
+        const payload = await readFile(getRuntimeStatePath(config), "utf8");
+        const parsed = JSON.parse(payload);
+        if (typeof parsed.pid !== "number" || !Number.isFinite(parsed.pid)) {
+            return null;
+        }
+        return {
+            pid: Math.trunc(parsed.pid),
+            origin: typeof parsed.origin === "string" ? parsed.origin : config.origin,
+            port: typeof parsed.port === "number" ? parsed.port : config.port,
+            baseUrl: typeof parsed.baseUrl === "string" ? parsed.baseUrl : config.baseUrl,
+            startedAt: typeof parsed.startedAt === "string" ? parsed.startedAt : new Date(0).toISOString()
+        };
+    }
+    catch {
+        return null;
+    }
+}
+function processExists(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return !(error instanceof Error) || !("code" in error) || error.code !== "ESRCH";
+    }
+}
+async function waitForProcessExit(pid, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        if (!processExists(pid)) {
+            return true;
+        }
+        await new Promise((resolve) => setTimeout(resolve, HEALTHCHECK_INTERVAL_MS));
+    }
+    return !processExists(pid);
+}
 function isLocalOrigin(origin) {
     try {
         return LOCAL_HOSTNAMES.has(new URL(origin).hostname.toLowerCase());
@@ -87,9 +146,13 @@ function spawnManagedRuntime(config, plan) {
             managedRuntimeChild = null;
             managedRuntimeKey = null;
         }
+        void clearRuntimeState(config);
     });
     managedRuntimeChild = child;
     managedRuntimeKey = runtimeKey(config);
+    void writeRuntimeState(config, child.pid).catch(() => {
+        // State tracking is best effort. Runtime health checks remain authoritative.
+    });
 }
 async function waitForRuntime(config, timeoutMs) {
     const deadline = Date.now() + timeoutMs;
@@ -134,3 +197,61 @@ export function primeForgeRuntime(config) {
         // Keep plugin registration non-blocking. Failures surface on first real call.
     });
 }
+export async function stopForgeRuntime(config) {
+    if (!isLocalOrigin(config.origin)) {
+        return {
+            ok: false,
+            stopped: false,
+            managed: false,
+            message: "Forge stop only supports local plugin-managed runtimes. Remote Forge targets must be stopped where they are hosted.",
+            pid: null
+        };
+    }
+    const state = await readRuntimeState(config);
+    if (!state) {
+        return {
+            ok: true,
+            stopped: false,
+            managed: false,
+            message: (await isForgeHealthy(config, HEALTHCHECK_TIMEOUT_MS))
+                ? "Forge is running, but it does not look like a plugin-managed runtime. Stop it where it was started."
+                : "Forge is not running through the plugin-managed local runtime.",
+            pid: null
+        };
+    }
+    if (!processExists(state.pid)) {
+        await clearRuntimeState(config);
+        return {
+            ok: true,
+            stopped: false,
+            managed: true,
+            message: "The saved Forge runtime PID was stale. The plugin-managed runtime is already stopped.",
+            pid: state.pid
+        };
+    }
+    process.kill(state.pid, "SIGTERM");
+    if (!(await waitForProcessExit(state.pid, 5_000))) {
+        process.kill(state.pid, "SIGKILL");
+        if (!(await waitForProcessExit(state.pid, 2_000))) {
+            return {
+                ok: false,
+                stopped: false,
+                managed: true,
+                message: `Forge runtime pid ${state.pid} did not stop cleanly.`,
+                pid: state.pid
+            };
+        }
+    }
+    if (managedRuntimeChild?.pid === state.pid) {
+        managedRuntimeChild = null;
+        managedRuntimeKey = null;
+    }
+    await clearRuntimeState(config);
+    return {
+        ok: true,
+        stopped: true,
+        managed: true,
+        message: `Stopped the plugin-managed Forge runtime on ${config.baseUrl}.`,
+        pid: state.pid
+    };
+}

package/dist/openclaw/routes.js

@@ -1,4 +1,5 @@
 import { canBootstrapOperatorSession, callConfiguredForgeApi, expectForgeSuccess, readJsonRequestBody, readSingleHeaderValue, requireApiToken, writeForgeProxyResponse, writePluginError, writeRedirectResponse } from "./api-client.js";
+import { stopForgeRuntime } from "./local-runtime.js";
 import { collectSupportedPluginApiRouteKeys, makeApiRouteKey } from "./parity.js";
 function passthroughSearch(path, url) {
     return `${path}${url.search}`;
@@ -374,6 +375,9 @@ export function registerForgePluginCli(api, config) {
         command.command("ui").description("Print the Forge UI entrypoint").action(async () => {
             console.log(JSON.stringify({ webAppUrl: await resolveForgeUiUrl(config), pluginUiRoute: "/forge/v1/ui" }, null, 2));
         });
+        command.command("stop").description("Stop the local Forge runtime when it was auto-started by the OpenClaw plugin").action(async () => {
+            console.log(JSON.stringify(await stopForgeRuntime(config), null, 2));
+        });
         command.command("doctor").description("Run plugin connectivity and curated route diagnostics").action(async () => {
             console.log(JSON.stringify(await runDoctor(config), null, 2));
         });

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "forge-openclaw-plugin",
   "name": "Forge",
   "description": "Curated OpenClaw adapter for the Forge collaboration API, UI entrypoint, and localhost auto-start runtime.",
-  "version": "0.2.10",
+  "version": "0.2.11",
   "skills": [
     "./skills"
   ],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forge-openclaw-plugin",
-  "version": "0.2.10",
+  "version": "0.2.11",
   "description": "Curated OpenClaw adapter for the Forge collaboration API, UI entrypoint, and localhost auto-start runtime.",
   "type": "module",
   "license": "MIT",

package/skills/forge-openclaw/SKILL.md

@@ -16,6 +16,8 @@ Forge data location rule:
 - on a linked repo-local install, this usually means `<repo>/openclaw-plugin/data/forge.sqlite`
 - if the user wants the data somewhere else for persistence, backup, or manual control, tell them to set `plugins.entries["forge-openclaw-plugin"].config.dataRoot` and restart the OpenClaw gateway
 - if the user asks where the data is stored or how to move it, explain the current default plainly and show the exact config field
+- if the user wants to stop a plugin-managed local Forge runtime cleanly, tell them to run `forge stop`
+- `forge stop` only shuts down a runtime that the OpenClaw plugin auto-started itself; if Forge was started manually elsewhere, it will say so instead of killing random local processes
 
 Use these exact entity meanings when deciding what the user is describing.