create-principles-disciple 1.104.0 → 1.104.2

package/console/dist/server/routes/update.js

@@ -5,11 +5,19 @@ import { execSync } from 'child_process';
 import semver from 'semver';
 import { sendSuccess, sendError, sendMethodNotAllowed, sendBadRequest, sendNotFound, } from '../utils/response.js';
 import { appendUpdateHistory } from './update-history.js';
+import { checkOpenClawGateway, stopOpenClawGateway, restartOpenClawGateway, } from '../utils/gateway.js';
 // ---------------------------------------------------------------------------
 // Constants
 // ---------------------------------------------------------------------------
-const NPM_REGISTRY_LATEST = 'https://registry.npmjs.org/create-principles-disciple/latest';
+// Fix: compare against the PLUGIN package (principles-disciple), not the
+// installer package (create-principles-disciple). These are independently
+// versioned — comparing them caused a permanent false "update available".
+const NPM_REGISTRY_LATEST = 'https://registry.npmjs.org/principles-disciple/latest';
 const WORKSPACE_FILES = ['AGENTS.md', 'SOUL.md', 'USER.md', 'CLAUDE.md'];
+// Directories to skip during backup and diff. node_modules contains native
+// .node addons locked by the gateway/console processes (EPERM on copyfile),
+// npm symlinks/junctions, and thousands of regenerable files.
+const SKIP_DIRS = new Set(['node_modules']);
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
@@ -64,6 +72,10 @@ async function readJsonBody(req) {
 function isString(value) {
     return typeof value === 'string';
 }
+// rc-2: type guard for parsed JSON objects (avoid `as` cast).
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
 function isValidMergeStrategy(value) {
     return typeof value === 'string' && (value === 'smart' || value === 'overwrite' || value === 'keep');
 }
@@ -80,14 +92,27 @@ function validatePathInWorkspace(target, workspaceDir) {
 // ---------------------------------------------------------------------------
 // Core update operations (inline to avoid cross-package import)
 // ---------------------------------------------------------------------------
-function copyDirRecursive(src, dest) {
+/**
+ * Recursively copy a directory tree.
+ *
+ * skipDirs: directory names to skip at every recursion level (e.g. node_modules).
+ * Symlinks are skipped to avoid Windows junction EPERM on copyFileSync.
+ */
+function copyDirRecursive(src, dest, skipDirs) {
+    const skip = skipDirs ?? new Set();
     fs.mkdirSync(dest, { recursive: true });
     const entries = fs.readdirSync(src, { withFileTypes: true });
     for (const entry of entries) {
+        if (skip.has(entry.name))
+            continue;
+        // Skip symlinks — on Windows, npm junctions cause EPERM when copyFileSync
+        // tries to read them as regular files. They are regenerable (npm install).
+        if (entry.isSymbolicLink())
+            continue;
         const srcPath = path.join(src, entry.name);
         const destPath = path.join(dest, entry.name);
         if (entry.isDirectory()) {
-            copyDirRecursive(srcPath, destPath);
+            copyDirRecursive(srcPath, destPath, skipDirs);
         }
         else {
             fs.copyFileSync(srcPath, destPath);
@@ -103,14 +128,17 @@ function copyFileTo(src, dest) {
         fs.mkdirSync(dir, { recursive: true });
     fs.copyFileSync(src, dest);
 }
-function getAllFilesLocal(dir) {
+function getAllFilesLocal(dir, skipDirs) {
+    const skip = skipDirs ?? new Set();
     const result = [];
     try {
         const entries = fs.readdirSync(dir, { withFileTypes: true });
         for (const entry of entries) {
+            if (skip.has(entry.name))
+                continue;
             const fullPath = path.join(dir, entry.name);
             if (entry.isDirectory()) {
-                const subFiles = getAllFilesLocal(fullPath);
+                const subFiles = getAllFilesLocal(fullPath, skipDirs);
                 result.push(...subFiles.map(f => path.join(entry.name, f)));
             }
             else {
@@ -125,8 +153,8 @@ function computeDiffLocal(currentDir, newDir) {
     const modified = [];
     const added = [];
     const deleted = [];
-    const currentFiles = getAllFilesLocal(currentDir);
-    const newFiles = getAllFilesLocal(newDir);
+    const currentFiles = getAllFilesLocal(currentDir, SKIP_DIRS);
+    const newFiles = getAllFilesLocal(newDir, SKIP_DIRS);
     const currentSet = new Set(currentFiles);
     const newSet = new Set(newFiles);
     for (const file of currentFiles) {
@@ -151,6 +179,19 @@ function computeDiffLocal(currentDir, newDir) {
     }
     return { modified, added, deleted };
 }
+/**
+ * Detect whether PD is also installed for the Codex host.
+ *
+ * The Web UI update only covers the OpenClaw extension directory. If Codex
+ * is installed (~/.codex/hooks.json or ~/.pd/codex/ exists), the user needs
+ * to know that the Codex adapter (@principles/codex-adapter) is NOT updated
+ * by this mechanism.
+ */
+function detectCodexInstall() {
+    const codexHooks = path.join(os.homedir(), '.codex', 'hooks.json');
+    const pdCodexDir = path.join(os.homedir(), '.pd', 'codex');
+    return fs.existsSync(codexHooks) || fs.existsSync(pdCodexDir);
+}
 async function doCheckForUpdates(currentVersion) {
     try {
         const controller = new AbortController();
@@ -163,30 +204,39 @@ async function doCheckForUpdates(currentVersion) {
             if (!response.ok)
                 throw new Error(`HTTP ${response.status}`);
             const rawData = await response.json();
-            if (typeof rawData !== 'object' || rawData === null)
+            if (!isRecord(rawData))
                 throw new Error('Invalid registry response');
-            const data = rawData;
-            if (typeof data.version !== 'string')
+            if (typeof rawData.version !== 'string')
                 throw new Error('Invalid registry response: missing version');
-            latestVersion = data.version;
+            latestVersion = rawData.version;
         }
         finally {
             clearTimeout(timeoutId);
         }
+        // Fetch release notes from GitHub for the latest version (best-effort,
+        // non-blocking — if it fails, the UI still shows version info without notes).
+        let changelog = '';
+        try {
+            const ghResponse = await fetch(`https://api.github.com/repos/csuzngjh/principles/releases/tags/v${latestVersion}`, { signal: AbortSignal.timeout(5000), headers: { Accept: 'application/vnd.github.v3+json' } });
+            if (ghResponse.ok) {
+                const ghData = await ghResponse.json();
+                if (isRecord(ghData) && typeof ghData.body === 'string') {
+                    changelog = ghData.body;
+                }
+            }
+        }
+        catch { /* best-effort — changelog is optional */ }
         return {
             hasUpdate: semver.gt(latestVersion, currentVersion),
             currentVersion,
             latestVersion,
+            changelog,
         };
     }
     catch (error) {
         return {
             hasUpdate: false,
             currentVersion,
-            // Contract with the UI (UpdatePage.tsx) requires latestVersion to be a
-            // string. When the registry check fails we don't know the latest version,
-            // so emit an empty string to keep the response shape stable and let the
-            // UI surface `error` instead of crashing the whole page.
             latestVersion: '',
             error: error instanceof Error ? error.message : 'Unknown error',
         };
@@ -225,6 +275,21 @@ async function doApplyUpdate(options, workspaceDir) {
     const { targetDir, mergeStrategy, createBackup } = options;
     let backupPath = undefined;
     let appliedChanges = false;
+    let gatewayWasStopped = false;
+    const codexInstalled = detectCodexInstall();
+    // Fix 5: stop the OpenClaw gateway before file mutations to release file
+    // locks on native modules. Best-effort — if `openclaw` is not in PATH or
+    // the gateway isn't running, we proceed (dist/*.js files are not locked).
+    const gatewayStatus = await checkOpenClawGateway();
+    if (gatewayStatus.isRunning) {
+        const stopRes = stopOpenClawGateway();
+        if (stopRes.ok) {
+            gatewayWasStopped = true;
+        }
+        // If stop failed, proceed anyway — the file operations below don't touch
+        // node_modules (excluded from backup and diff), so locks on native modules
+        // don't matter. dist/*.js files are read-once by Node, never locked.
+    }
     try {
         // 0. Save current version BEFORE any changes
         const fromVersion = readCurrentVersion(targetDir) ?? 'unknown';
@@ -241,22 +306,27 @@ async function doApplyUpdate(options, workspaceDir) {
         const tarball = dist && typeof dist.tarball === 'string' ? dist.tarball : undefined;
         if (!tarball)
             return { success: false, message: 'Missing tarball URL in registry response' };
-        // 2. Create backup if requested
+        // 2. Create backup if requested (Fix 2: skip node_modules to avoid EPERM
+        //    from locked native modules and npm symlinks/junctions)
         if (createBackup) {
             const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
             backupPath = path.join(path.dirname(targetDir), `.pd-backup-${timestamp}`);
-            copyDirRecursive(targetDir, backupPath);
+            copyDirRecursive(targetDir, backupPath, SKIP_DIRS);
         }
         // 3. Download and extract new version (with timeout + retry)
-        const tempDir = path.join(os.tmpdir(), `pd-update-${Date.now()}`);
-        fs.mkdirSync(tempDir, { recursive: true });
+        const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'pd-update-'));
         const dlResponse = await fetchWithRetry(tarball, 'Download');
         const buffer = Buffer.from(await dlResponse.arrayBuffer());
         const tarballPath = path.join(tempDir, 'package.tgz');
         fs.writeFileSync(tarballPath, buffer);
         execSync(`tar xzf "${tarballPath}" -C "${tempDir}" --strip-components=1`, { stdio: 'pipe' });
         fs.unlinkSync(tarballPath);
-        // 4. Compute diff and apply
+        // 4. Compute diff and apply.
+        // Fix 3: we ONLY apply modified + added files. We deliberately skip ALL
+        // deletions — the tarball (principles-disciple) only contains dist/,
+        // scripts/, templates/, openclaw.plugin.json, package.json, while the
+        // installed extension also has console/, core/, pd-cli/, node_modules/,
+        // bin/, docs/. Deleting those would destroy the installation.
         appliedChanges = true;
         const diff = computeDiffLocal(targetDir, tempDir);
         const updatedFiles = [];
@@ -285,16 +355,7 @@ async function doApplyUpdate(options, workspaceDir) {
             copyFileTo(path.join(tempDir, file), path.join(targetDir, file));
             updatedFiles.push(file);
         }
-        for (const file of diff.deleted) {
-            // Only delete non-workspace files, or workspace files when strategy is overwrite
-            if (isWorkspaceFile(file) && mergeStrategy !== 'overwrite') {
-                continue;
-            }
-            const filePath = path.join(targetDir, file);
-            if (fs.existsSync(filePath))
-                fs.unlinkSync(filePath);
-            updatedFiles.push(file);
-        }
+        // Fix 3: deletions intentionally skipped — see comment above.
         // 5. Update package.json version
         const pkgPath = path.join(targetDir, 'package.json');
         if (fs.existsSync(pkgPath)) {
@@ -320,9 +381,14 @@ async function doApplyUpdate(options, workspaceDir) {
             updatedFiles,
             backupPath,
             newVersion: toVersion,
+            // Signal to the UI that Codex adapter was not covered by this update.
+            partialUpdate: codexInstalled,
         };
     }
     catch (error) {
+        // Fix 6: EPERM-aware structured error (rc-9 / cli-6: reason + nextAction)
+        const errorMsg = error instanceof Error ? error.message : 'Unknown error';
+        const isLockError = /EPERM|EBUSY|EACCES|operation not permitted/i.test(errorMsg);
         // Clean up backup only if we failed before applying any file changes
         if (!appliedChanges && backupPath && fs.existsSync(backupPath)) {
             try {
@@ -330,11 +396,26 @@ async function doApplyUpdate(options, workspaceDir) {
             }
             catch { /* best effort */ }
         }
+        if (isLockError) {
+            return {
+                success: false,
+                message: 'Update blocked by file lock (OpenClaw gateway may still be running)',
+                reason: 'file_locked',
+                nextAction: '请重启电脑后再次尝试更新。',
+            };
+        }
         return {
             success: false,
-            message: error instanceof Error ? error.message : 'Unknown error',
+            message: errorMsg,
         };
     }
+    finally {
+        // Fix 5: restart the gateway if we stopped it (even on failure), so the
+        // user is never left without a running gateway. Mirrors installer.ts behavior.
+        if (gatewayWasStopped) {
+            restartOpenClawGateway();
+        }
+    }
 }
 async function doRollbackUpdate(options, workspaceDir) {
     const { targetDir, backupDir } = options;
@@ -342,9 +423,11 @@ async function doRollbackUpdate(options, workspaceDir) {
         if (!fs.existsSync(backupDir)) {
             return { success: false, message: 'Backup not found' };
         }
-        if (fs.existsSync(targetDir)) {
-            fs.rmSync(targetDir, { recursive: true, force: true });
-        }
+        // Fix 4: do NOT rmSync the entire targetDir — the backup excludes
+        // node_modules, so a delete+restore would leave the installation without
+        // dependencies. Instead, overwrite from backup: modified files (dist/,
+        // package.json, etc.) get the backup version, while node_modules/console/
+        // core/ (not in the backup) are left untouched.
         copyDirRecursive(backupDir, targetDir);
         // Record rollback history
         appendUpdateHistory(workspaceDir, {
@@ -363,6 +446,178 @@ async function doRollbackUpdate(options, workspaceDir) {
     }
 }
 // ---------------------------------------------------------------------------
+// Full update — inline tarball download + file copy (no external installer)
+// ---------------------------------------------------------------------------
+// The installer package bundles ALL sub-packages (plugin, console, core,
+// pd-cli). We download it directly and copy the pre-built dist/ directories.
+// This is seconds-fast (no npm install) and requires no CLI/npx — the entire
+// operation happens inside the console HTTP handler.
+const NPM_REGISTRY_INSTALLER = 'https://registry.npmjs.org/create-principles-disciple/latest';
+/**
+ * Compare two dependency maps for meaningful differences.
+ * Ignores `@principles/core` (always `file:./core` in bundled packages).
+ */
+function depsMeaningfullyChanged(oldDeps, newDeps) {
+    const a = {};
+    const b = {};
+    // Normalize: strip @principles/core (file: ref is not a real version)
+    for (const [k, v] of Object.entries(oldDeps ?? {})) {
+        if (k !== '@principles/core')
+            a[k] = v;
+    }
+    for (const [k, v] of Object.entries(newDeps ?? {})) {
+        if (k !== '@principles/core')
+            b[k] = v;
+    }
+    const aKeys = Object.keys(a).sort();
+    const bKeys = Object.keys(b).sort();
+    if (aKeys.length !== bKeys.length)
+        return true;
+    return aKeys.some((k, i) => bKeys[i] !== k || a[k] !== b[k]);
+}
+async function doInlineFullUpdate(workspaceDir) {
+    const extDir = resolvePluginDir(workspaceDir);
+    // 1. Stop gateway (releases native module locks held by the gateway process)
+    const gatewayStatus = await checkOpenClawGateway();
+    let gatewayWasStopped = false;
+    if (gatewayStatus.isRunning) {
+        const stopRes = stopOpenClawGateway();
+        if (stopRes.ok)
+            gatewayWasStopped = true;
+    }
+    // Capture version before changes
+    const fromVersion = readCurrentVersion(extDir) ?? 'unknown';
+    let tempDir;
+    try {
+        // 2. Fetch installer package info from npm
+        const response = await fetchWithRetry(NPM_REGISTRY_INSTALLER, 'Installer registry check');
+        const rawData = await response.json();
+        if (!isRecord(rawData))
+            return { success: false, message: 'Invalid registry response', requiresRestart: false };
+        const toVersion = typeof rawData.version === 'string' ? rawData.version : undefined;
+        const dist = isRecord(rawData.dist) ? rawData.dist : null;
+        const tarball = dist && typeof dist.tarball === 'string' ? dist.tarball : undefined;
+        if (!tarball)
+            return { success: false, message: 'Missing tarball URL', requiresRestart: false };
+        // 3. Download + extract tarball (contains plugin/, console/, core/, pd-cli/)
+        tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'pd-full-update-'));
+        const dlResponse = await fetchWithRetry(tarball, 'Download');
+        const buffer = Buffer.from(await dlResponse.arrayBuffer());
+        const tarballPath = path.join(tempDir, 'package.tgz');
+        fs.writeFileSync(tarballPath, buffer);
+        execSync(`tar xzf "${tarballPath}" -C "${tempDir}" --strip-components=1`, { stdio: 'pipe' });
+        fs.unlinkSync(tarballPath);
+        // 4. Detect dependency changes (informational — logged but not blocking;
+        //    the .js files are still updated; node_modules stays as-is)
+        let depsChanged = false;
+        const newPkgPath = path.join(tempDir, 'plugin', 'package.json');
+        const oldPkgPath = path.join(extDir, 'package.json');
+        if (fs.existsSync(newPkgPath) && fs.existsSync(oldPkgPath)) {
+            try {
+                const newPkg = JSON.parse(fs.readFileSync(newPkgPath, 'utf-8'));
+                const oldPkg = JSON.parse(fs.readFileSync(oldPkgPath, 'utf-8'));
+                if (isRecord(newPkg) && isRecord(oldPkg)) {
+                    depsChanged = depsMeaningfullyChanged(isRecord(oldPkg.dependencies) ? oldPkg.dependencies : undefined, isRecord(newPkg.dependencies) ? newPkg.dependencies : undefined);
+                }
+            }
+            catch { /* best-effort comparison */ }
+        }
+        // 5. Copy files — 4 subdirectory mappings
+        //    a. plugin/* → extDir/* (flattened, skip node_modules)
+        const pluginSrc = path.join(tempDir, 'plugin');
+        if (fs.existsSync(pluginSrc)) {
+            copyDirRecursive(pluginSrc, extDir, SKIP_DIRS);
+        }
+        //    b. console/ → extDir/console/ (overwrite dist/ files; do NOT rmSync —
+        //       console/node_modules/ may contain locked native modules like
+        //       better-sqlite3 that the running console process holds via dlopen)
+        const consoleSrc = path.join(tempDir, 'console');
+        const consoleDest = path.join(extDir, 'console');
+        if (fs.existsSync(consoleSrc)) {
+            copyDirRecursive(consoleSrc, consoleDest, SKIP_DIRS);
+        }
+        //    c. core/ → extDir/core/ (overwrite, skip node_modules for safety)
+        const coreSrc = path.join(tempDir, 'core');
+        const coreDest = path.join(extDir, 'core');
+        if (fs.existsSync(coreSrc)) {
+            copyDirRecursive(coreSrc, coreDest, SKIP_DIRS);
+        }
+        //    d. pd-cli/dist + package.json → extDir/pd-cli/ (overwrite only,
+        //       do NOT rmSync — preserves node_modules symlinks created at install)
+        const pdCliSrc = path.join(tempDir, 'pd-cli');
+        const pdCliDest = path.join(extDir, 'pd-cli');
+        if (fs.existsSync(pdCliSrc)) {
+            const distSrc = path.join(pdCliSrc, 'dist');
+            const distDest = path.join(pdCliDest, 'dist');
+            if (fs.existsSync(distSrc)) {
+                if (fs.existsSync(distDest))
+                    fs.rmSync(distDest, { recursive: true, force: true });
+                copyDirRecursive(distSrc, distDest);
+            }
+            const pkgSrc = path.join(pdCliSrc, 'package.json');
+            if (fs.existsSync(pkgSrc)) {
+                copyFileTo(pkgSrc, path.join(pdCliDest, 'package.json'));
+            }
+        }
+        // 6. Cleanup temp dir
+        if (tempDir && fs.existsSync(tempDir)) {
+            fs.rmSync(tempDir, { recursive: true, force: true });
+        }
+        // 7. Record history
+        const newVersion = readCurrentVersion(extDir) ?? toVersion ?? 'unknown';
+        appendUpdateHistory(workspaceDir, {
+            fromVersion,
+            toVersion: newVersion,
+            success: true,
+        });
+        return {
+            success: true,
+            message: depsChanged
+                ? 'Full update completed. Some dependencies may have changed — if you encounter issues, restart your computer and try again.'
+                : 'Full update completed successfully',
+            newVersion,
+            requiresRestart: true,
+        };
+    }
+    catch (error) {
+        // Clean up temp dir on failure
+        if (tempDir && fs.existsSync(tempDir)) {
+            try {
+                fs.rmSync(tempDir, { recursive: true, force: true });
+            }
+            catch { /* best effort */ }
+        }
+        const errorMsg = error instanceof Error ? error.message : 'Unknown error';
+        const isLockError = /EPERM|EBUSY|EACCES|operation not permitted/i.test(errorMsg);
+        // Record failed update
+        appendUpdateHistory(workspaceDir, {
+            fromVersion,
+            toVersion: 'failed',
+            success: false,
+        });
+        if (isLockError) {
+            return {
+                success: false,
+                message: 'Update blocked by a file lock. The OpenClaw gateway may still be running.',
+                reason: 'file_locked',
+                nextAction: 'Please restart your computer, then try the update again.',
+                requiresRestart: false,
+            };
+        }
+        return {
+            success: false,
+            message: errorMsg,
+            requiresRestart: false,
+        };
+    }
+    finally {
+        // 8. Restart gateway regardless of success/failure
+        if (gatewayWasStopped) {
+            restartOpenClawGateway();
+        }
+    }
+}
+// ---------------------------------------------------------------------------
 // Route handler
 // ---------------------------------------------------------------------------
 export async function handleUpdateRoute(req, res, workspaceDir, subPath) {
@@ -378,17 +633,19 @@ export async function handleUpdateRoute(req, res, workspaceDir, subPath) {
             // 返回 degraded 状态 + reason，而非 500。前端 validateUpdateStatus 要求
             // currentVersion/latestVersion 为 string，hasUpdate 为 boolean。
             const currentVersion = readCurrentVersion(pluginDir);
+            const codexInstalled = detectCodexInstall();
             if (!currentVersion) {
                 sendSuccess(res, {
                     hasUpdate: false,
                     currentVersion: 'unknown',
                     latestVersion: '',
+                    codexInstalled,
                     error: 'Could not determine current version (plugin not installed)',
                 });
                 return;
             }
             const result = await doCheckForUpdates(currentVersion);
-            sendSuccess(res, result);
+            sendSuccess(res, { ...result, codexInstalled });
         }
         catch (err) {
             sendError(res, 500, 'update_check_error', err instanceof Error ? err.message : 'Unknown error');
@@ -483,5 +740,20 @@ export async function handleUpdateRoute(req, res, workspaceDir, subPath) {
         }
         return;
     }
+    // POST /apply-full — inline tarball download + file copy (no external installer)
+    if (subPath === '/apply-full') {
+        if (req.method !== 'POST') {
+            sendMethodNotAllowed(res);
+            return;
+        }
+        try {
+            const result = await doInlineFullUpdate(workspaceDir);
+            sendSuccess(res, result);
+        }
+        catch (err) {
+            sendError(res, 500, 'update_apply_full_error', err instanceof Error ? err.message : 'Unknown error');
+        }
+        return;
+    }
     sendNotFound(res, `Update route not found: ${subPath}`);
 }

package/console/dist/server/utils/gateway.d.ts

@@ -0,0 +1,25 @@
+export interface OpenClawGatewayStatus {
+    isRunning: boolean;
+    port?: number;
+    pid?: number;
+}
+export interface GatewayControlResult {
+    ok: boolean;
+    error?: string;
+}
+/**
+ * Check whether the OpenClaw gateway is currently running.
+ * Reads the configured port from openclaw.json, probes 127.0.0.1:<port>,
+ * and (best-effort) resolves the owning PID.
+ */
+export declare function checkOpenClawGateway(): Promise<OpenClawGatewayStatus>;
+/**
+ * Stop the OpenClaw gateway service. Call before mutating the plugin ext dir
+ * to release file locks held on native modules (EPERM on backup copyfile).
+ */
+export declare function stopOpenClawGateway(): GatewayControlResult;
+/**
+ * Start the OpenClaw gateway service (inverse of stopOpenClawGateway).
+ * Called after update completes (success or failure) to leave the gateway running.
+ */
+export declare function restartOpenClawGateway(): GatewayControlResult;

package/console/dist/server/utils/gateway.js

@@ -0,0 +1,131 @@
+/**
+ * OpenClaw gateway control utilities for the update flow.
+ *
+ * Ported from create-principles-disciple/src/utils/env.ts (PRI-230 / commit 6efc0afa).
+ * Lives in pd-console so the Web UI update handler can stop/restart the gateway
+ * around file mutations without cross-package imports.
+ *
+ * rc-9: every function returns a structured result instead of throwing.
+ */
+import { execSync } from 'child_process';
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+import * as net from 'net';
+// rc-2: type guard instead of `as` cast on parsed JSON.
+function isRecord(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+// ---------------------------------------------------------------------------
+// Gateway detection
+// ---------------------------------------------------------------------------
+/**
+ * Resolve the OpenClaw config directory.
+ * Priority: OPENCLAW_HOME env var > ~/.openclaw
+ */
+function resolveOpenClawConfigDir() {
+    const envHome = process.env.OPENCLAW_HOME;
+    if (envHome && envHome.trim().length > 0)
+        return path.resolve(envHome);
+    return path.join(os.homedir(), '.openclaw');
+}
+/**
+ * Read the gateway port from ~/.openclaw/openclaw.json → { gateway: { port } }.
+ * Returns null if the file or field is missing/malformed.
+ */
+function readOpenClawPort() {
+    const configPath = path.join(resolveOpenClawConfigDir(), 'openclaw.json');
+    if (!fs.existsSync(configPath))
+        return null;
+    try {
+        const raw = fs.readFileSync(configPath, 'utf-8');
+        const config = JSON.parse(raw);
+        if (!isRecord(config))
+            return null;
+        const gateway = config.gateway;
+        if (!isRecord(gateway))
+            return null;
+        const port = gateway.port;
+        if (typeof port === 'number' && port > 0 && port < 65536)
+            return port;
+    }
+    catch { /* ignore */ }
+    return null;
+}
+function checkPortListening(port) {
+    return new Promise((resolve) => {
+        const socket = new net.Socket();
+        const timeout = 2000;
+        socket.setTimeout(timeout);
+        socket.on('connect', () => { socket.destroy(); resolve(true); });
+        socket.on('error', () => { socket.destroy(); resolve(false); });
+        socket.on('timeout', () => { socket.destroy(); resolve(false); });
+        socket.connect(port, '127.0.0.1');
+    });
+}
+/**
+ * Check whether the OpenClaw gateway is currently running.
+ * Reads the configured port from openclaw.json, probes 127.0.0.1:<port>,
+ * and (best-effort) resolves the owning PID.
+ */
+export async function checkOpenClawGateway() {
+    const port = readOpenClawPort();
+    if (!port)
+        return { isRunning: false };
+    const listening = await checkPortListening(port);
+    if (!listening)
+        return { isRunning: false };
+    let pid = undefined;
+    try {
+        if (process.platform === 'win32') {
+            const output = execSync(`powershell -NoProfile -Command "(Get-NetTCPConnection -LocalPort ${port} -State Listen -ErrorAction SilentlyContinue).OwningProcess"`, { encoding: 'utf-8', timeout: 5000 }).trim();
+            if (output) {
+                const [firstLine] = output.split('\n');
+                if (firstLine)
+                    pid = parseInt(firstLine.trim(), 10);
+            }
+        }
+        else {
+            const output = execSync(`lsof -i :${port} -t -sTCP:LISTEN 2>/dev/null`, { encoding: 'utf-8', timeout: 5000 }).trim();
+            if (output) {
+                const [firstLine] = output.split('\n');
+                if (firstLine)
+                    pid = parseInt(firstLine.trim(), 10);
+            }
+        }
+    }
+    catch { /* ignore */ }
+    return { isRunning: true, port, pid };
+}
+// ---------------------------------------------------------------------------
+// Gateway stop / restart
+// ---------------------------------------------------------------------------
+/**
+ * Run `openclaw gateway <subcommand>` (service-level: launchd/systemd/schtasks).
+ * rc-9: never throws — returns {ok:false, error} so the caller can degrade
+ * with a structured reason + nextAction instead of crashing mid-update.
+ */
+function runGatewayServiceCommand(subcommand) {
+    try {
+        execSync(`openclaw gateway ${subcommand}`, { stdio: 'pipe', encoding: 'utf-8', timeout: 15000 });
+        return { ok: true };
+    }
+    catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        return { ok: false, error: `\`openclaw gateway ${subcommand}\` failed: ${msg}` };
+    }
+}
+/**
+ * Stop the OpenClaw gateway service. Call before mutating the plugin ext dir
+ * to release file locks held on native modules (EPERM on backup copyfile).
+ */
+export function stopOpenClawGateway() {
+    return runGatewayServiceCommand('stop');
+}
+/**
+ * Start the OpenClaw gateway service (inverse of stopOpenClawGateway).
+ * Called after update completes (success or failure) to leave the gateway running.
+ */
+export function restartOpenClawGateway() {
+    return runGatewayServiceCommand('start');
+}

package/console/dist/ui/App.d.ts

@@ -1 +1 @@
-export declare function App(): import("react/jsx-runtime").JSX.Element;
+export declare function App(): import("react").JSX.Element;