forge-openclaw-plugin 0.2.11 → 0.2.12

package/README.md

@@ -72,21 +72,22 @@ Current OpenClaw builds should use package discovery:
 
 ```bash
 openclaw plugins install forge-openclaw-plugin
-openclaw gateway restart
-```
-
-If your OpenClaw install does not enable it automatically, run:
-
-```bash
 openclaw plugins enable forge-openclaw-plugin
+node -e 'const fs=require("fs"); const p=process.env.HOME+"/.openclaw/openclaw.json"; const j=JSON.parse(fs.readFileSync(p,"utf8")); j.plugins ??= {}; j.plugins.allow = Array.from(new Set([...(j.plugins.allow || []), "forge-openclaw-plugin"])); fs.writeFileSync(p, JSON.stringify(j, null, 2)+"\n");'
 openclaw gateway restart
+openclaw forge health
 ```
 
+`openclaw plugins enable forge-openclaw-plugin` marks the plugin enabled, but it does not guarantee that `plugins.allow` was repaired. The `node -e ...` command above preserves the current allow list and appends `"forge-openclaw-plugin"` if it is missing.
+
 For release-parity local development from this repo:
 
 ```bash
 openclaw plugins install ./projects/forge/openclaw-plugin
+openclaw plugins enable forge-openclaw-plugin
+node -e 'const fs=require("fs"); const p=process.env.HOME+"/.openclaw/openclaw.json"; const j=JSON.parse(fs.readFileSync(p,"utf8")); j.plugins ??= {}; j.plugins.allow = Array.from(new Set([...(j.plugins.allow || []), "forge-openclaw-plugin"])); fs.writeFileSync(p, JSON.stringify(j, null, 2)+"\n");'
 openclaw gateway restart
+openclaw forge health
 ```
 
 Equivalent config:
@@ -202,13 +203,16 @@ 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:
+If you want to manage that plugin-managed local runtime cleanly, use:
 
 ```bash
-forge stop
+openclaw forge start
+openclaw forge stop
+openclaw forge restart
+openclaw forge status
 ```
 
-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.
+These commands only manage the runtime when it was auto-started by the OpenClaw plugin. If Forge was started manually some other way, they tell you that instead of killing unrelated processes.
 
 ## Publishing and listing
 

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

@@ -6,6 +6,34 @@ export type ForgeRuntimeStopResult = {
     message: string;
     pid: number | null;
 };
+export type ForgeRuntimeStartResult = {
+    ok: boolean;
+    started: boolean;
+    managed: boolean;
+    message: string;
+    pid: number | null;
+    baseUrl: string;
+};
+export type ForgeRuntimeStatusResult = {
+    ok: boolean;
+    running: boolean;
+    healthy: boolean;
+    managed: boolean;
+    message: string;
+    pid: number | null;
+    baseUrl: string;
+};
+export type ForgeRuntimeRestartResult = {
+    ok: boolean;
+    restarted: boolean;
+    managed: boolean;
+    message: string;
+    pid: number | null;
+    baseUrl: string;
+};
 export declare function ensureForgeRuntimeReady(config: ForgePluginConfig): Promise<void>;
+export declare function startForgeRuntime(config: ForgePluginConfig): Promise<ForgeRuntimeStartResult>;
 export declare function primeForgeRuntime(config: ForgePluginConfig): void;
 export declare function stopForgeRuntime(config: ForgePluginConfig): Promise<ForgeRuntimeStopResult>;
+export declare function getForgeRuntimeStatus(config: ForgePluginConfig): Promise<ForgeRuntimeStatusResult>;
+export declare function restartForgeRuntime(config: ForgePluginConfig): Promise<ForgeRuntimeRestartResult>;

package/dist/openclaw/local-runtime.js

@@ -192,6 +192,39 @@ export async function ensureForgeRuntimeReady(config) {
     });
     return startupPromise;
 }
+export async function startForgeRuntime(config) {
+    if (!isLocalOrigin(config.origin)) {
+        return {
+            ok: false,
+            started: false,
+            managed: false,
+            message: "Forge start only supports local plugin-managed runtimes. Remote Forge targets must be started where they are hosted.",
+            pid: null,
+            baseUrl: config.baseUrl
+        };
+    }
+    const existingState = await readRuntimeState(config);
+    if (existingState && processExists(existingState.pid) && (await isForgeHealthy(config, HEALTHCHECK_TIMEOUT_MS))) {
+        return {
+            ok: true,
+            started: false,
+            managed: true,
+            message: `Forge is already running on ${config.baseUrl}.`,
+            pid: existingState.pid,
+            baseUrl: config.baseUrl
+        };
+    }
+    await ensureForgeRuntimeReady(config);
+    const state = await readRuntimeState(config);
+    return {
+        ok: true,
+        started: true,
+        managed: true,
+        message: `Started the plugin-managed Forge runtime on ${config.baseUrl}.`,
+        pid: state?.pid ?? managedRuntimeChild?.pid ?? null,
+        baseUrl: config.baseUrl
+    };
+}
 export function primeForgeRuntime(config) {
     void ensureForgeRuntimeReady(config).catch(() => {
         // Keep plugin registration non-blocking. Failures surface on first real call.
@@ -255,3 +288,111 @@ export async function stopForgeRuntime(config) {
         pid: state.pid
     };
 }
+export async function getForgeRuntimeStatus(config) {
+    const healthy = await isForgeHealthy(config, HEALTHCHECK_TIMEOUT_MS);
+    const state = await readRuntimeState(config);
+    const pid = state?.pid ?? null;
+    const managed = Boolean(state);
+    const running = healthy || (pid !== null && processExists(pid));
+    if (!isLocalOrigin(config.origin)) {
+        return {
+            ok: healthy,
+            running: healthy,
+            healthy,
+            managed: false,
+            message: healthy
+                ? `Forge is reachable at ${config.baseUrl}. Runtime lifecycle is managed remotely.`
+                : `Forge is not reachable at ${config.baseUrl}. Runtime lifecycle is managed remotely.`,
+            pid: null,
+            baseUrl: config.baseUrl
+        };
+    }
+    if (managed && pid !== null && !processExists(pid)) {
+        await clearRuntimeState(config);
+        return {
+            ok: true,
+            running: false,
+            healthy: false,
+            managed: true,
+            message: "The saved Forge runtime PID was stale. The plugin-managed runtime is stopped.",
+            pid,
+            baseUrl: config.baseUrl
+        };
+    }
+    if (healthy && managed) {
+        return {
+            ok: true,
+            running: true,
+            healthy: true,
+            managed: true,
+            message: `Forge is running and healthy on ${config.baseUrl}.`,
+            pid,
+            baseUrl: config.baseUrl
+        };
+    }
+    if (healthy) {
+        return {
+            ok: true,
+            running: true,
+            healthy: true,
+            managed: false,
+            message: `Forge is running on ${config.baseUrl}, but it does not look like a plugin-managed runtime.`,
+            pid: null,
+            baseUrl: config.baseUrl
+        };
+    }
+    if (managed) {
+        return {
+            ok: true,
+            running: false,
+            healthy: false,
+            managed: true,
+            message: "The plugin-managed Forge runtime is stopped.",
+            pid,
+            baseUrl: config.baseUrl
+        };
+    }
+    return {
+        ok: true,
+        running: false,
+        healthy: false,
+        managed: false,
+        message: "Forge is not running through the plugin-managed local runtime.",
+        pid: null,
+        baseUrl: config.baseUrl
+    };
+}
+export async function restartForgeRuntime(config) {
+    if (!isLocalOrigin(config.origin)) {
+        return {
+            ok: false,
+            restarted: false,
+            managed: false,
+            message: "Forge restart only supports local plugin-managed runtimes. Remote Forge targets must be restarted where they are hosted.",
+            pid: null,
+            baseUrl: config.baseUrl
+        };
+    }
+    const stopResult = await stopForgeRuntime(config);
+    if (!stopResult.ok) {
+        return {
+            ok: false,
+            restarted: false,
+            managed: stopResult.managed,
+            message: stopResult.message,
+            pid: stopResult.pid,
+            baseUrl: config.baseUrl
+        };
+    }
+    const startResult = await startForgeRuntime(config);
+    return {
+        ok: startResult.ok,
+        restarted: startResult.ok,
+        managed: true,
+        message: startResult.ok
+            ? `Restarted the plugin-managed Forge runtime on ${config.baseUrl}.`
+            : startResult.message,
+        pid: startResult.pid,
+        baseUrl: config.baseUrl
+    };
+}

package/dist/openclaw/routes.js

@@ -1,5 +1,5 @@
 import { canBootstrapOperatorSession, callConfiguredForgeApi, expectForgeSuccess, readJsonRequestBody, readSingleHeaderValue, requireApiToken, writeForgeProxyResponse, writePluginError, writeRedirectResponse } from "./api-client.js";
-import { stopForgeRuntime } from "./local-runtime.js";
+import { getForgeRuntimeStatus, restartForgeRuntime, startForgeRuntime, stopForgeRuntime } from "./local-runtime.js";
 import { collectSupportedPluginApiRouteKeys, makeApiRouteKey } from "./parity.js";
 function passthroughSearch(path, url) {
     return `${path}${url.search}`;
@@ -375,9 +375,18 @@ 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("start").description("Start the local Forge runtime when it is managed by the OpenClaw plugin").action(async () => {
+            console.log(JSON.stringify(await startForgeRuntime(config), 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("restart").description("Restart the local Forge runtime when it is managed by the OpenClaw plugin").action(async () => {
+            console.log(JSON.stringify(await restartForgeRuntime(config), null, 2));
+        });
+        command.command("status").description("Report whether the local Forge runtime is running and whether it is plugin-managed").action(async () => {
+            console.log(JSON.stringify(await getForgeRuntimeStatus(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.11",
+  "version": "0.2.12",
   "skills": [
     "./skills"
   ],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forge-openclaw-plugin",
-  "version": "0.2.11",
+  "version": "0.2.12",
   "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,8 +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
+- if the user wants to manage a plugin-managed local Forge runtime cleanly, tell them to run `openclaw forge start`, `openclaw forge stop`, `openclaw forge restart`, or `openclaw forge status`
+- these commands only manage a runtime that the OpenClaw plugin auto-started itself; if Forge was started manually elsewhere, they will say so instead of killing random local processes
 
 Use these exact entity meanings when deciding what the user is describing.