forge-openclaw-plugin 0.2.11 → 0.2.13

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,26 @@ 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.
+
+If the local runtime fails to come up, check the plugin-managed runtime log at:
+
+```bash
+~/.openclaw/logs/forge-openclaw-plugin/127.0.0.1-4317.log
+```
+
+On clean installs, the plugin now also repairs missing bundled runtime dependencies on first local start before it launches Forge.
+
+The startup error now points at that log file when the child process exits before Forge becomes healthy.
 
 ## 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

@@ -1,5 +1,5 @@
 import { spawn } from "node:child_process";
-import { existsSync } from "node:fs";
+import { closeSync, existsSync, mkdirSync, openSync } from "node:fs";
 import { homedir } from "node:os";
 import path from "node:path";
 import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
@@ -10,7 +10,10 @@ const HEALTHCHECK_TIMEOUT_MS = 1_500;
 const HEALTHCHECK_INTERVAL_MS = 250;
 let managedRuntimeChild = null;
 let managedRuntimeKey = null;
+let managedRuntimeLogPath = null;
+let lastRuntimeExitDetails = null;
 let startupPromise = null;
+const dependencyInstallPromises = new Map();
 function runtimeKey(config) {
     return `${config.origin}:${config.port}`;
 }
@@ -26,7 +29,8 @@ async function writeRuntimeState(config, pid) {
         origin: config.origin,
         port: config.port,
         baseUrl: config.baseUrl,
-        startedAt: new Date().toISOString()
+        startedAt: new Date().toISOString(),
+        logPath: managedRuntimeLogPath
     };
     await writeFile(statePath, `${JSON.stringify(payload, null, 2)}\n`, "utf8");
 }
@@ -45,7 +49,8 @@ async function readRuntimeState(config) {
             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()
+            startedAt: typeof parsed.startedAt === "string" ? parsed.startedAt : new Date(0).toISOString(),
+            logPath: typeof parsed.logPath === "string" ? parsed.logPath : null
         };
     }
     catch {
@@ -82,6 +87,86 @@ function isLocalOrigin(origin) {
 function getCurrentModuleRoot() {
     return path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
 }
+function getRuntimeLogPath(config) {
+    const origin = new URL(config.origin).hostname.toLowerCase().replace(/[^a-z0-9._-]+/g, "-");
+    return path.join(homedir(), ".openclaw", "logs", "forge-openclaw-plugin", `${origin}-${config.port}.log`);
+}
+function openRuntimeLogFile(logPath) {
+    mkdirSync(path.dirname(logPath), { recursive: true });
+    return openSync(logPath, "a");
+}
+function isPackagedServerPlan(plan) {
+    return plan.entryFile.endsWith(path.join("dist", "server", "index.js"));
+}
+function getNpmInvocation() {
+    const binDir = path.dirname(process.execPath);
+    const npmCli = process.platform === "win32" ? path.join(binDir, "npm.cmd") : path.join(binDir, "npm");
+    if (existsSync(npmCli)) {
+        return {
+            command: process.execPath,
+            args: [npmCli]
+        };
+    }
+    return {
+        command: "npm",
+        args: []
+    };
+}
+async function getMissingRuntimeDependencies(packageRoot) {
+    const packageJsonPath = path.join(packageRoot, "package.json");
+    const packageJson = JSON.parse(await readFile(packageJsonPath, "utf8"));
+    const dependencyNames = Object.keys(packageJson.dependencies ?? {});
+    return dependencyNames.filter((dependencyName) => !existsSync(path.join(packageRoot, "node_modules", dependencyName, "package.json")));
+}
+async function installMissingRuntimeDependencies(packageRoot, logPath) {
+    const { command, args } = getNpmInvocation();
+    const logFd = openRuntimeLogFile(logPath);
+    try {
+        await new Promise((resolve, reject) => {
+            const child = spawn(command, [...args, "install", "--omit=dev", "--silent", "--ignore-scripts"], {
+                cwd: packageRoot,
+                env: process.env,
+                stdio: ["ignore", logFd, logFd]
+            });
+            child.once("error", reject);
+            child.once("exit", (code, signal) => {
+                if (code === 0) {
+                    resolve();
+                    return;
+                }
+                reject(new Error(`npm dependency install exited with ${signal ? `signal ${signal}` : `code ${code ?? "unknown"}`}`));
+            });
+        });
+    }
+    finally {
+        closeSync(logFd);
+    }
+}
+async function ensurePackagedRuntimeDependencies(plan, config) {
+    if (!isPackagedServerPlan(plan)) {
+        return;
+    }
+    const missingDependencies = await getMissingRuntimeDependencies(plan.packageRoot);
+    if (missingDependencies.length === 0) {
+        return;
+    }
+    const logPath = getRuntimeLogPath(config);
+    managedRuntimeLogPath = logPath;
+    const installKey = plan.packageRoot;
+    const existingInstall = dependencyInstallPromises.get(installKey);
+    if (existingInstall) {
+        return existingInstall;
+    }
+    const installPromise = installMissingRuntimeDependencies(plan.packageRoot, logPath)
+        .catch((error) => {
+        throw new Error(`Forge runtime dependencies are missing (${missingDependencies.join(", ")}) and automatic install failed. Check logs at ${logPath}. Cause: ${error instanceof Error ? error.message : String(error)}`);
+    })
+        .finally(() => {
+        dependencyInstallPromises.delete(installKey);
+    });
+    dependencyInstallPromises.set(installKey, installPromise);
+    return installPromise;
+}
 function resolveLaunchPlan() {
     const moduleRoot = getCurrentModuleRoot();
     // Published or linked plugin package runtime.
@@ -126,8 +211,10 @@ async function isForgeHealthy(config, timeoutMs) {
     }
 }
 function spawnManagedRuntime(config, plan) {
-    const isPackagedServer = plan.entryFile.endsWith(path.join("dist", "server", "index.js"));
+    const isPackagedServer = isPackagedServerPlan(plan);
     const args = isPackagedServer ? [plan.entryFile] : [plan.entryFile, path.join(plan.packageRoot, "server", "src", "index.ts")];
+    const logPath = getRuntimeLogPath(config);
+    const logFd = openRuntimeLogFile(logPath);
     const child = spawn(process.execPath, args, {
         cwd: plan.packageRoot,
         env: {
@@ -137,11 +224,20 @@ function spawnManagedRuntime(config, plan) {
             FORGE_BASE_PATH: "/forge/",
             ...(config.dataRoot ? { FORGE_DATA_ROOT: config.dataRoot } : {})
         },
-        stdio: "ignore",
+        stdio: ["ignore", logFd, logFd],
         detached: true
     });
+    closeSync(logFd);
     child.unref();
-    child.once("exit", () => {
+    managedRuntimeLogPath = logPath;
+    lastRuntimeExitDetails = null;
+    child.once("exit", (code, signal) => {
+        lastRuntimeExitDetails = {
+            pid: child.pid ?? -1,
+            code,
+            signal,
+            logPath
+        };
         if (managedRuntimeChild === child) {
             managedRuntimeChild = null;
             managedRuntimeKey = null;
@@ -154,15 +250,31 @@ function spawnManagedRuntime(config, plan) {
         // State tracking is best effort. Runtime health checks remain authoritative.
     });
 }
-async function waitForRuntime(config, timeoutMs) {
+function formatRuntimeFailure(details, config) {
+    if (!details) {
+        return `Forge local runtime did not become healthy at ${config.baseUrl} within ${STARTUP_TIMEOUT_MS}ms`;
+    }
+    const suffix = details.logPath ? ` Check logs at ${details.logPath}.` : "";
+    if (details.signal) {
+        return `Forge local runtime exited before becoming healthy at ${config.baseUrl} (signal ${details.signal}).${suffix}`;
+    }
+    if (typeof details.code === "number") {
+        return `Forge local runtime exited before becoming healthy at ${config.baseUrl} (code ${details.code}).${suffix}`;
+    }
+    return `Forge local runtime exited before becoming healthy at ${config.baseUrl}.${suffix}`;
+}
+async function waitForRuntime(config, timeoutMs, expectedPid) {
     const deadline = Date.now() + timeoutMs;
     while (Date.now() < deadline) {
         if (await isForgeHealthy(config, HEALTHCHECK_TIMEOUT_MS)) {
             return;
         }
+        if (expectedPid !== null && lastRuntimeExitDetails?.pid === expectedPid) {
+            throw new Error(formatRuntimeFailure(lastRuntimeExitDetails, config));
+        }
         await new Promise((resolve) => setTimeout(resolve, HEALTHCHECK_INTERVAL_MS));
     }
-    throw new Error(`Forge local runtime did not become healthy at ${config.baseUrl} within ${timeoutMs}ms`);
+    throw new Error(formatRuntimeFailure(lastRuntimeExitDetails, config));
 }
 export async function ensureForgeRuntimeReady(config) {
     if (!isLocalOrigin(config.origin)) {
@@ -183,15 +295,69 @@ export async function ensureForgeRuntimeReady(config) {
         if (await isForgeHealthy(config, HEALTHCHECK_TIMEOUT_MS)) {
             return;
         }
+        await ensurePackagedRuntimeDependencies(plan, config);
         if (!managedRuntimeChild || managedRuntimeKey !== key || managedRuntimeChild.killed) {
             spawnManagedRuntime(config, plan);
         }
-        await waitForRuntime(config, STARTUP_TIMEOUT_MS);
+        await waitForRuntime(config, STARTUP_TIMEOUT_MS, managedRuntimeChild?.pid ?? null);
     })().finally(() => {
         startupPromise = null;
     });
     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 && (await isForgeHealthy(config, HEALTHCHECK_TIMEOUT_MS))) {
+        return {
+            ok: true,
+            started: false,
+            managed: false,
+            message: `Forge is already running on ${config.baseUrl}, but it does not look like a plugin-managed runtime.`,
+            pid: null,
+            baseUrl: config.baseUrl
+        };
+    }
+    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);
+    if (!state && (await isForgeHealthy(config, HEALTHCHECK_TIMEOUT_MS))) {
+        return {
+            ok: true,
+            started: false,
+            managed: false,
+            message: `Forge is healthy on ${config.baseUrl}, but it does not look like a plugin-managed runtime.`,
+            pid: null,
+            baseUrl: config.baseUrl
+        };
+    }
+    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 +421,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.13",
   "skills": [
     "./skills"
   ],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forge-openclaw-plugin",
-  "version": "0.2.11",
+  "version": "0.2.13",
   "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.