@okclaw-build/cli 1.0.0-beta.6 → 1.0.0-beta.60

package/dist/utils/install-safety.js

@@ -0,0 +1,97 @@
+import { isAbsolute, resolve, sep } from 'node:path';
+import { BUNDLED_PLUGINS, CHANNEL_ALIASES, CHANNEL_NPM_PACKAGES, OKCLAW_TMP_DIR, OPENCLAW_HOME, OPENCLAW_WORKSPACE, } from './constants.js';
+const CHANNEL_NAMES = new Set([
+    ...Object.keys(CHANNEL_NPM_PACKAGES),
+    ...Object.keys(CHANNEL_ALIASES),
+    ...BUNDLED_PLUGINS,
+    's3',
+]);
+const NAME_TOKEN_PATTERN = /^[A-Za-z0-9._-]+$/;
+const VERSION_PATTERN = /^[A-Za-z0-9._+-]+$/;
+const SHELL_METACHAR_PATTERN = /[`$;|<>]/;
+const CONTROL_PATTERN = /[\x00-\x1F\x7F]/;
+export function parseInstallComponent(component) {
+    if (component === 'openclaw')
+        return { kind: 'openclaw', raw: component };
+    if (component.startsWith('skill:')) {
+        const skillName = component.slice('skill:'.length);
+        return { kind: 'skill', raw: component, skillName: assertSafeInstallName('skill', skillName) };
+    }
+    if (CHANNEL_NAMES.has(component)) {
+        const channelName = CHANNEL_ALIASES[component] ?? component;
+        return { kind: 'channel', raw: component, channelName: assertSafeInstallName('channel', channelName) };
+    }
+    throw new Error(`Unsupported install component: ${component}`);
+}
+export function assertSafeInstallName(kind, name) {
+    const message = `Invalid ${kind} name: ${name}`;
+    const maxLength = kind === 'skill' ? 128 : 64;
+    if (!name || name.length > maxLength || name === '.' || name === '..') {
+        throw new Error(message);
+    }
+    if (!NAME_TOKEN_PATTERN.test(name) || name.includes('..')) {
+        throw new Error(message);
+    }
+    return name;
+}
+export function assertSafePackageVersion(version) {
+    if (!version
+        || version.length > 128
+        || !VERSION_PATTERN.test(version)
+        || version.includes('..')
+        || version.includes('/')
+        || version.includes('\\')
+        || /\s/.test(version)
+        || CONTROL_PATTERN.test(version)) {
+        throw new Error(`Invalid package version: ${version}`);
+    }
+    return version;
+}
+export function parsePackageSource(raw) {
+    if (hasUnsafePackageSourceChars(raw)) {
+        throw new Error(`Invalid packageUrl: ${raw}`);
+    }
+    let parsed;
+    try {
+        parsed = new URL(raw);
+    }
+    catch {
+        parsed = undefined;
+    }
+    if (parsed?.protocol === 'http:' || parsed?.protocol === 'https:') {
+        return { kind: 'remote', url: raw };
+    }
+    if (parsed && parsed.protocol !== 'file:') {
+        throw new Error(`Invalid packageUrl: ${raw}`);
+    }
+    if (!isAbsolute(raw)) {
+        throw new Error(`Invalid packageUrl: local package must be an absolute path: ${raw}`);
+    }
+    if (raw.split(/[\\/]+/).includes('..')) {
+        throw new Error(`Invalid packageUrl: ${raw}`);
+    }
+    return { kind: 'local', path: raw };
+}
+export function resolveInside(baseDir, ...segments) {
+    const base = resolve(baseDir);
+    const target = resolve(base, ...segments);
+    if (target !== base && !target.startsWith(`${base}${sep}`)) {
+        throw new Error(`Resolved path outside base directory: ${target}`);
+    }
+    return target;
+}
+export function channelExtensionDir(channelName) {
+    return resolveInside(OPENCLAW_HOME, 'extensions', assertSafeInstallName('channel', channelName));
+}
+export function skillInstallDir(skillName) {
+    return resolveInside(OPENCLAW_WORKSPACE, 'skills', assertSafeInstallName('skill', skillName));
+}
+export function tmpInstallPath(fileName) {
+    return resolveInside(OKCLAW_TMP_DIR, assertSafeInstallName('skill', fileName));
+}
+function hasUnsafePackageSourceChars(raw) {
+    return SHELL_METACHAR_PATTERN.test(raw)
+        || CONTROL_PATTERN.test(raw)
+        || /\s/.test(raw);
+}
+//# sourceMappingURL=install-safety.js.map

package/dist/utils/install-safety.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"install-safety.js","sourceRoot":"","sources":["../../src/utils/install-safety.ts"],"names":[],"mappings":"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"}

package/dist/utils/logger.d.ts

@@ -1,3 +1,13 @@
+/**
+ * 人类可读 log。
+ *
+ * ndjson 模式下：所有业务级 log（info / warn / success / error）静默。
+ *   - info/warn/success 本就无关紧要，静默避免污染 stdout 结构化流
+ *   - error 也静默（bug#5 修）：业务错误必须通过 emitter.end(false, code, { error: msg }) 承载，
+ *     与 design 契约对齐（stderr 仅给真正的崩溃栈，由 registerExitHandlers 的 uncaughtException 打印）
+ *
+ * 调用方注意：ndjson 模式下调 error(msg) 不会让用户看见消息，务必把 msg 塞进 emitter.end 的 fields。
+ */
 export declare function info(msg: string): void;
 export declare function warn(msg: string): void;
 export declare function error(msg: string): void;

package/dist/utils/logger.js

@@ -1,5 +1,32 @@
-export function info(msg) { console.log(`[okclaw] ${msg}`); }
-export function warn(msg) { console.log(`[okclaw] WARN: ${msg}`); }
-export function error(msg) { console.error(`[okclaw] ERROR: ${msg}`); }
-export function success(msg) { console.log(`[okclaw] ✓ ${msg}`); }
+import { isNdjson } from '../output/mode.js';
+/**
+ * 人类可读 log。
+ *
+ * ndjson 模式下：所有业务级 log（info / warn / success / error）静默。
+ *   - info/warn/success 本就无关紧要，静默避免污染 stdout 结构化流
+ *   - error 也静默（bug#5 修）：业务错误必须通过 emitter.end(false, code, { error: msg }) 承载，
+ *     与 design 契约对齐（stderr 仅给真正的崩溃栈，由 registerExitHandlers 的 uncaughtException 打印）
+ *
+ * 调用方注意：ndjson 模式下调 error(msg) 不会让用户看见消息，务必把 msg 塞进 emitter.end 的 fields。
+ */
+export function info(msg) {
+    if (isNdjson())
+        return;
+    console.log(`[okclaw] ${msg}`);
+}
+export function warn(msg) {
+    if (isNdjson())
+        return;
+    console.log(`[okclaw] WARN: ${msg}`);
+}
+export function error(msg) {
+    if (isNdjson())
+        return;
+    console.error(`[okclaw] ERROR: ${msg}`);
+}
+export function success(msg) {
+    if (isNdjson())
+        return;
+    console.log(`[okclaw] ✓ ${msg}`);
+}
 //# sourceMappingURL=logger.js.map

package/dist/utils/logger.js.map

@@ -1 +1 @@
-{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../src/utils/logger.ts"],"names":[],"mappings":"AAAA,MAAM,UAAU,IAAI,CAAC,GAAW,IAAI,OAAO,CAAC,GAAG,CAAC,YAAY,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC;AACrE,MAAM,UAAU,IAAI,CAAC,GAAW,IAAI,OAAO,CAAC,GAAG,CAAC,kBAAkB,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC;AAC3E,MAAM,UAAU,KAAK,CAAC,GAAW,IAAI,OAAO,CAAC,KAAK,CAAC,mBAAmB,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC;AAC/E,MAAM,UAAU,OAAO,CAAC,GAAW,IAAI,OAAO,CAAC,GAAG,CAAC,cAAc,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC"}
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../src/utils/logger.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAE7C;;;;;;;;;GASG;AAEH,MAAM,UAAU,IAAI,CAAC,GAAW;IAC9B,IAAI,QAAQ,EAAE;QAAE,OAAO;IACvB,OAAO,CAAC,GAAG,CAAC,YAAY,GAAG,EAAE,CAAC,CAAC;AACjC,CAAC;AAED,MAAM,UAAU,IAAI,CAAC,GAAW;IAC9B,IAAI,QAAQ,EAAE;QAAE,OAAO;IACvB,OAAO,CAAC,GAAG,CAAC,kBAAkB,GAAG,EAAE,CAAC,CAAC;AACvC,CAAC;AAED,MAAM,UAAU,KAAK,CAAC,GAAW;IAC/B,IAAI,QAAQ,EAAE;QAAE,OAAO;IACvB,OAAO,CAAC,KAAK,CAAC,mBAAmB,GAAG,EAAE,CAAC,CAAC;AAC1C,CAAC;AAED,MAAM,UAAU,OAAO,CAAC,GAAW;IACjC,IAAI,QAAQ,EAAE;QAAE,OAAO;IACvB,OAAO,CAAC,GAAG,CAAC,cAAc,GAAG,EAAE,CAAC,CAAC;AACnC,CAAC"}

package/dist/utils/mirror.js

@@ -4,6 +4,20 @@ import { NPM_REGISTRY, PIP_INDEX_URL, PIP_TRUSTED_HOST } from './constants.js';
 export async function configureMirrors() {
     info('Configuring China mirrors...');
     await shell(`npm config set registry ${NPM_REGISTRY}`).catch(() => { });
+    // 第三方插件（如 @soimy/dingtalk）的 devDependencies 偶发会因为上游版本漂移
+    // 出现 peer dep 冲突（实例：oxlint@1.63.0 要求 oxlint-tsgolint>=0.22.1，但插件
+    // 钉死 ^0.18.0），npm 10 默认严格 peer 解析会报 ERESOLVE 直接挂掉
+    // openclaw plugins install 内部的 npm install。openclaw 没暴露 install flag 给我们传，
+    // 设成全局 npm config 是唯一能影响它的方式。lint/format devDep 的版本拉新对运行时
+    // 无影响，让 npm 用旧 peer 解析逻辑通过即可。
+    await shell(`npm config set legacy-peer-deps true`).catch(() => { });
+    // 部分 npm 包（如 openclaw 依赖的 libsignal-node）用 git+ssh://git@github.com/...
+    // 引用 GitHub 仓库。云主机 root 账户默认没有 GitHub SSH key 会拉取失败。
+    // 这里把 ssh://git@github.com/ 和 git@github.com: 都重写成 https://github.com/（匿名可读）。
+    // 注意: 同一个 URL name 下要写多个 insteadOf 必须用 --add，否则第二次 set 会覆盖第一次。
+    await shell(`git config --global --unset-all url."https://github.com/".insteadOf 2>/dev/null || true`).catch(() => { });
+    await shell(`git config --global --add url."https://github.com/".insteadOf ssh://git@github.com/`).catch(() => { });
+    await shell(`git config --global --add url."https://github.com/".insteadOf git@github.com:`).catch(() => { });
     // Use /root/.pip — not ~/
     await shell(`mkdir -p /root/.pip && cat > /root/.pip/pip.conf << 'EOF'
 [global]

package/dist/utils/mirror.js.map

@@ -1 +1 @@
-{"version":3,"file":"mirror.js","sourceRoot":"","sources":["../../src/utils/mirror.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,EAAE,IAAI,EAAE,MAAM,aAAa,CAAC;AACnC,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAE/E,MAAM,CAAC,KAAK,UAAU,gBAAgB;IACpC,IAAI,CAAC,8BAA8B,CAAC,CAAC;IAErC,MAAM,KAAK,CAAC,2BAA2B,YAAY,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;IAEvE,0BAA0B;IAC1B,MAAM,KAAK,CAAC;;cAEA,aAAa;iBACV,gBAAgB;IAC7B,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;IAEpB,IAAI,CAAC,qBAAqB,CAAC,CAAC;AAC9B,CAAC"}
+{"version":3,"file":"mirror.js","sourceRoot":"","sources":["../../src/utils/mirror.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,EAAE,IAAI,EAAE,MAAM,aAAa,CAAC;AACnC,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAE/E,MAAM,CAAC,KAAK,UAAU,gBAAgB;IACpC,IAAI,CAAC,8BAA8B,CAAC,CAAC;IAErC,MAAM,KAAK,CAAC,2BAA2B,YAAY,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;IAEvE,wDAAwD;IACxD,iEAAiE;IACjE,kDAAkD;IAClD,2EAA2E;IAC3E,0DAA0D;IAC1D,8BAA8B;IAC9B,MAAM,KAAK,CAAC,sCAAsC,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;IAEpE,wEAAwE;IACxE,qDAAqD;IACrD,8EAA8E;IAC9E,+DAA+D;IAC/D,MAAM,KAAK,CACT,yFAAyF,CAC1F,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;IAClB,MAAM,KAAK,CACT,qFAAqF,CACtF,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;IAClB,MAAM,KAAK,CACT,+EAA+E,CAChF,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;IAElB,0BAA0B;IAC1B,MAAM,KAAK,CAAC;;cAEA,aAAa;iBACV,gBAAgB;IAC7B,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;IAEpB,IAAI,CAAC,qBAAqB,CAAC,CAAC;AAC9B,CAAC"}

package/dist/utils/openclaw-config-cli.d.ts

@@ -0,0 +1,19 @@
+export declare class OpenclawConfigCliError extends Error {
+    readonly cmd: string;
+    readonly exitCode: number;
+    readonly stdout: string;
+    readonly stderr: string;
+    constructor(cmd: string, exitCode: number, stdout: string, stderr: string);
+}
+export interface CliRunner {
+    run(args: string[]): {
+        exitCode: number;
+        stdout: string;
+        stderr: string;
+    };
+}
+export declare const defaultCliRunner: CliRunner;
+export declare function configGet(path: string, runner?: CliRunner): unknown | undefined;
+export declare function configSet(path: string, valueJson: string, runner?: CliRunner): void;
+export declare function configUnset(path: string, runner?: CliRunner): void;
+export declare function configValidate(runner?: CliRunner): boolean;

package/dist/utils/openclaw-config-cli.js

@@ -0,0 +1,81 @@
+import { execFileSync } from 'node:child_process';
+export class OpenclawConfigCliError extends Error {
+    cmd;
+    exitCode;
+    stdout;
+    stderr;
+    constructor(cmd, exitCode, stdout, stderr) {
+        super(`openclaw ${cmd} failed (exit ${exitCode}): ${stderr || stdout}`);
+        this.cmd = cmd;
+        this.exitCode = exitCode;
+        this.stdout = stdout;
+        this.stderr = stderr;
+    }
+}
+function stringifyOutput(value) {
+    if (typeof value === 'string')
+        return value;
+    if (Buffer.isBuffer(value))
+        return value.toString('utf8');
+    return '';
+}
+export const defaultCliRunner = {
+    run(args) {
+        try {
+            const stdout = execFileSync('openclaw', args, {
+                encoding: 'utf8',
+                stdio: ['ignore', 'pipe', 'pipe'],
+            });
+            return { exitCode: 0, stdout, stderr: '' };
+        }
+        catch (err) {
+            const error = err;
+            return {
+                exitCode: typeof error.status === 'number' ? error.status : 127,
+                stdout: stringifyOutput(error.stdout),
+                stderr: stringifyOutput(error.stderr || error.message),
+            };
+        }
+    },
+};
+function runOrThrow(args, runner = defaultCliRunner) {
+    const result = runner.run(args);
+    if (result.exitCode !== 0) {
+        throw new OpenclawConfigCliError(args.join(' '), result.exitCode, result.stdout, result.stderr);
+    }
+    return result;
+}
+function isNotFoundOutput(output) {
+    return /Config\s+path\s+not\s+found/i.test(output);
+}
+export function configGet(path, runner = defaultCliRunner) {
+    const args = ['config', 'get', path];
+    const result = runner.run(args);
+    if (result.exitCode !== 0) {
+        if (isNotFoundOutput(`${result.stderr}\n${result.stdout}`))
+            return undefined;
+        throw new OpenclawConfigCliError(args.join(' '), result.exitCode, result.stdout, result.stderr);
+    }
+    const stdout = result.stdout.trim();
+    if (!stdout)
+        return undefined;
+    try {
+        return JSON.parse(stdout);
+    }
+    catch {
+        // openclaw config get prints scalar string values as raw text without JSON
+        // quoting (e.g. `openviking` rather than `"openviking"`). number / bool / null
+        // are valid JSON literals so they parse above; only unquoted strings reach here.
+        return stdout;
+    }
+}
+export function configSet(path, valueJson, runner = defaultCliRunner) {
+    runOrThrow(['config', 'set', path, valueJson, '--strict-json'], runner);
+}
+export function configUnset(path, runner = defaultCliRunner) {
+    runOrThrow(['config', 'unset', path], runner);
+}
+export function configValidate(runner = defaultCliRunner) {
+    return runner.run(['config', 'validate']).exitCode === 0;
+}
+//# sourceMappingURL=openclaw-config-cli.js.map

package/dist/utils/openclaw-config-cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"openclaw-config-cli.js","sourceRoot":"","sources":["../../src/utils/openclaw-config-cli.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAElD,MAAM,OAAO,sBAAuB,SAAQ,KAAK;IAE7B;IACA;IACA;IACA;IAJlB,YACkB,GAAW,EACX,QAAgB,EAChB,MAAc,EACd,MAAc;QAE9B,KAAK,CAAC,YAAY,GAAG,iBAAiB,QAAQ,MAAM,MAAM,IAAI,MAAM,EAAE,CAAC,CAAC;QALxD,QAAG,GAAH,GAAG,CAAQ;QACX,aAAQ,GAAR,QAAQ,CAAQ;QAChB,WAAM,GAAN,MAAM,CAAQ;QACd,WAAM,GAAN,MAAM,CAAQ;IAGhC,CAAC;CACF;AAMD,SAAS,eAAe,CAAC,KAAc;IACrC,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC5C,IAAI,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC1D,OAAO,EAAE,CAAC;AACZ,CAAC;AAED,MAAM,CAAC,MAAM,gBAAgB,GAAc;IACzC,GAAG,CAAC,IAAc;QAChB,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,YAAY,CAAC,UAAU,EAAE,IAAI,EAAE;gBAC5C,QAAQ,EAAE,MAAM;gBAChB,KAAK,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC;aAClC,CAAC,CAAC;YACH,OAAO,EAAE,QAAQ,EAAE,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC;QAC7C,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,KAAK,GAAG,GAIb,CAAC;YACF,OAAO;gBACL,QAAQ,EAAE,OAAO,KAAK,CAAC,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG;gBAC/D,MAAM,EAAE,eAAe,CAAC,KAAK,CAAC,MAAM,CAAC;gBACrC,MAAM,EAAE,eAAe,CAAC,KAAK,CAAC,MAAM,IAAI,KAAK,CAAC,OAAO,CAAC;aACvD,CAAC;QACJ,CAAC;IACH,CAAC;CACF,CAAC;AAEF,SAAS,UAAU,CAAC,IAAc,EAAE,SAAoB,gBAAgB;IACtE,MAAM,MAAM,GAAG,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAChC,IAAI,MAAM,CAAC,QAAQ,KAAK,CAAC,EAAE,CAAC;QAC1B,MAAM,IAAI,sBAAsB,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC;IAClG,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,SAAS,gBAAgB,CAAC,MAAc;IACtC,OAAO,8BAA8B,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;AACrD,CAAC;AAED,MAAM,UAAU,SAAS,CAAC,IAAY,EAAE,SAAoB,gBAAgB;IAC1E,MAAM,IAAI,GAAG,CAAC,QAAQ,EAAE,KAAK,EAAE,IAAI,CAAC,CAAC;IACrC,MAAM,MAAM,GAAG,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAChC,IAAI,MAAM,CAAC,QAAQ,KAAK,CAAC,EAAE,CAAC;QAC1B,IAAI,gBAAgB,CAAC,GAAG,MAAM,CAAC,MAAM,KAAK,MAAM,CAAC,MAAM,EAAE,CAAC;YAAE,OAAO,SAAS,CAAC;QAC7E,MAAM,IAAI,sBAAsB,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC;IAClG,CAAC;IAED,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;IACpC,IAAI,CAAC,MAAM;QAAE,OAAO,SAAS,CAAC;IAC9B,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IAC5B,CAAC;IAAC,MAAM,CAAC;QACP,2EAA2E;QAC3E,+EAA+E;QAC/E,iFAAiF;QACjF,OAAO,MAAM,CAAC;IAChB,CAAC;AACH,CAAC;AAED,MAAM,UAAU,SAAS,CAAC,IAAY,EAAE,SAAiB,EAAE,SAAoB,gBAAgB;IAC7F,UAAU,CAAC,CAAC,QAAQ,EAAE,KAAK,EAAE,IAAI,EAAE,SAAS,EAAE,eAAe,CAAC,EAAE,MAAM,CAAC,CAAC;AAC1E,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,IAAY,EAAE,SAAoB,gBAAgB;IAC5E,UAAU,CAAC,CAAC,QAAQ,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,CAAC;AAChD,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,SAAoB,gBAAgB;IACjE,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC,CAAC,QAAQ,KAAK,CAAC,CAAC;AAC3D,CAAC"}

package/dist/utils/openclaw-daemon.d.ts

@@ -0,0 +1,58 @@
+/**
+ * 确保 gateway 的 systemd 服务已安装且能常驻。
+ * - `loginctl enable-linger`:systemd user 服务默认随最后一个登录会话退出而停,
+ *   开 linger 后才能在部署 SSH 断开后 / 主机重启后继续运行。
+ * - `openclaw gateway install --force`:幂等(重装覆盖),顺带在 openclaw 升级后
+ *   刷新 unit 的 ExecStart。
+ */
+export declare function installGatewayService(): Promise<void>;
+/** 启动 gateway(先确保 systemd 服务已装)。 */
+export declare function startGateway(): Promise<void>;
+/** 重启 gateway(先确保 systemd 服务已装)。 */
+export declare function restartGateway(): Promise<void>;
+/**
+ * 停掉 gateway:先停掉所有已知的 systemd unit(新 + 旧 unit 名),再按监听
+ * 端口兜底杀掉非 systemd 托管的残留进程。顺序见 {@link STOP_GATEWAY_UNITS}。
+ */
+export declare function stopGateway(): Promise<void>;
+/** gateway 运行状态。健康的唯一标准是端口已监听。 */
+export type GatewayState = 'listening' | 'starting' | 'down';
+/**
+ * 探测 gateway 状态。**健康的唯一标准是 18789 端口已监听** —— 进程 active
+ * 不等于对外可服务。
+ *
+ * - `listening`:端口已监听,健康。
+ * - `starting` :systemd 服务 active,但端口在 bounded wait 内始终没监听 ——
+ *   配置异常 / 启动卡住 / 仍在初始化,**不算健康**。
+ * - `down`     :systemd 服务非 active 且端口未监听。
+ *
+ * `openclaw gateway restart` 返回后服务立刻是 active,但 gateway 进程还要几秒
+ * 才 bind 端口。所以端口没起来、服务却 active 时给一段 bounded wait 覆盖这个
+ * 启动窗口;服务都不 active 则直接 `down`,不等。
+ */
+export declare function probeGatewayState(): Promise<GatewayState>;
+/**
+ * 清掉 systemd user 目录下的 gateway unit 残留。`openclaw gateway uninstall`
+ * 只删主 `.service` 文件,残留的 `.service.bak` 备份和 `.service.d/` drop-in
+ * 会在下次 install 时被 systemd 自动 merge 进来(注入过时的 env 等),必须一并清。
+ */
+export declare function cleanupGatewayServiceFiles(): Promise<void>;
+/**
+ * Best-effort stop of the openclaw gateway so cli operations have exclusive
+ * write access to openclaw.json + extensions/.
+ *
+ * Why this is needed: the gateway has a config file watcher that writes its
+ * own metadata back into openclaw.json on every config change. Concurrent
+ * writes during cli's cleanup / `openclaw plugins install` / `openclaw config
+ * set` race with that watcher and produce:
+ *   - ENOTEMPTY: rmdir '.../node_modules/.cache/jiti' (jiti cache write race)
+ *   - ConfigMutationConflictError: config changed since last load (hash check
+ *     in openclaw plugins install commit / openclaw config set atomic write)
+ *
+ * Bootstrap orchestrator (commands/install.ts) is responsible for restarting
+ * the gateway after the full component install pipeline finishes.
+ *
+ * @param context A short label for logs, e.g. "dingtalk install" or
+ *                "openclaw deployment defaults".
+ */
+export declare function stopDaemonForExclusiveAccess(context: string): Promise<void>;

package/dist/utils/openclaw-daemon.js

@@ -0,0 +1,154 @@
+import { shell, shellCapture } from './shell.js';
+import { info } from './logger.js';
+import { OPENCLAW_GATEWAY_PORT } from './constants.js';
+/**
+ * openclaw gateway 生命周期管理。
+ *
+ * 关键决策:gateway 交给 openclaw 自带的 systemd 服务管理,cli 不再自己用
+ * nohup + ps + pkill 管进程。
+ *
+ * 为什么:openclaw 2026.5 的 gateway 有自己的单实例 lock、restart-handoff、
+ * 进程改名(`openclaw` / `node`)机制。cli 旧实现按进程名 `openclaw-gateway`
+ * 识别 + nohup 拉起 + 手动 kill,实测都顶不住:
+ *   - 进程名匹配 0 个 → restart 存活检测恒失败,报 E_RESTART_FAILED
+ *     (即使 gateway 其实已经起来了)
+ *   - 改用 `openclaw gateway run --force` + nohup,会和 openclaw 自身的
+ *     lock / handoff 互相赛跑 → 双进程、端口悬空、健康检查 abnormal closure
+ * 而 `openclaw gateway install/start/stop/restart`(systemd user 服务)实测
+ * 连续重启始终单进程、端口干净、状态准确。所以一律走 openclaw 的 service 命令。
+ */
+// gateway / systemctl 命令的环境前缀。
+//
+// unset SUDO_*:cli 在非 root 登录的主机(如 AWS Ubuntu AMI 的 ubuntu 用户)
+//   上由 os-api 用 `sudo -H` 提权到 root 跑。`sudo -H` 把 HOME 设成 /root,
+//   于是 `openclaw gateway install` 把 unit 文件写进 /root/.config/systemd/user/;
+//   但 openclaw 又据 SUDO_USER 判定"当前用户是 ubuntu",enable 时跑的是
+//   `systemctl --machine ubuntu@ --user ...` —— 去 ubuntu 的 systemd 里找 unit,
+//   找不到 → "Unit file does not exist" → install 失败。unset 掉 SUDO_* 让
+//   openclaw 当成纯 root 调用,写 unit 与操作 systemd 都对着 root,一致。
+// XDG_RUNTIME_DIR:systemctl --user 需要它;非交互 SSH exec 下通常已由
+//   pam_systemd 注入,这里再兜底一次,防个别主机 sshd PAM 配置不注入。
+const SYSTEMD_ENV = 'unset SUDO_USER SUDO_UID SUDO_GID; ' +
+    'export XDG_RUNTIME_DIR="${XDG_RUNTIME_DIR:-/run/user/$(id -u)}"; ';
+// gateway 没被 systemd 接管时(老主机残留 / 异常)按监听端口兜底杀进程。
+// 覆盖 `openclaw` / `node` 两种进程名;且绝不会误杀正在执行本 CLI 的进程。
+// 用 awk 解析 `pid=NNN` 而不是 `grep -oP` —— grep 的 -P(PCRE,含 \K)是 GNU
+// 扩展,非 GNU 环境(BSD grep 等)会整条命令报错、兜底路径静默退化成 no-op。
+// awk -F'pid=' 把每个 `pid=` 后的字段数值化($i+0 取前导数字),POSIX 通用。
+const KILL_GATEWAY_BY_PORT = `ss -ltnHp 'sport = :${OPENCLAW_GATEWAY_PORT}' 2>/dev/null` +
+    ` | awk -F'pid=' '{for(i=2;i<=NF;i++){p=$i+0;if(p>0)print p}}'` +
+    ` | sort -u | xargs -r kill 2>/dev/null || true`;
+/**
+ * 确保 gateway 的 systemd 服务已安装且能常驻。
+ * - `loginctl enable-linger`:systemd user 服务默认随最后一个登录会话退出而停,
+ *   开 linger 后才能在部署 SSH 断开后 / 主机重启后继续运行。
+ * - `openclaw gateway install --force`:幂等(重装覆盖),顺带在 openclaw 升级后
+ *   刷新 unit 的 ExecStart。
+ */
+export async function installGatewayService() {
+    await shell(`loginctl enable-linger root 2>/dev/null || true`).catch(() => { });
+    await shell(`${SYSTEMD_ENV}openclaw gateway install --force --port ${OPENCLAW_GATEWAY_PORT}`);
+}
+/** 启动 gateway(先确保 systemd 服务已装)。 */
+export async function startGateway() {
+    await installGatewayService();
+    await shell(`${SYSTEMD_ENV}openclaw gateway start`);
+}
+/** 重启 gateway(先确保 systemd 服务已装)。 */
+export async function restartGateway() {
+    await installGatewayService();
+    await shell(`${SYSTEMD_ENV}openclaw gateway restart`);
+}
+// 停掉所有已知的 gateway systemd unit。新版 openclaw 的 unit 名是
+// openclaw-gateway.service;老主机可能是 openclaw.service(早期 cli 用过的
+// unit 名,--user / system 两种 scope 都覆盖)。
+//
+// **必须在按端口 kill 之前先停 unit**:先停 unit,systemd 视为"主动停止"、
+// 不会触发 Restart=;反过来先 kill 进程,systemd 当成异常退出,会按
+// Restart=always/on-failure 立刻把 gateway 拉回来 —— stopDaemonForExclusiveAccess
+// 就拿不到真正的独占窗口,config watcher 写配置的竞争(ConfigMutationConflict)复现。
+// 按端口 kill 只作为非 systemd 托管残留进程的兜底,不能替代停 supervisor。
+const STOP_GATEWAY_UNITS = `${SYSTEMD_ENV}` +
+    `openclaw gateway stop 2>/dev/null || true; ` +
+    `systemctl --user stop openclaw-gateway.service 2>/dev/null || true; ` +
+    `systemctl --user stop openclaw.service 2>/dev/null || true; ` +
+    `systemctl stop openclaw.service 2>/dev/null || true`;
+/**
+ * 停掉 gateway:先停掉所有已知的 systemd unit(新 + 旧 unit 名),再按监听
+ * 端口兜底杀掉非 systemd 托管的残留进程。顺序见 {@link STOP_GATEWAY_UNITS}。
+ */
+export async function stopGateway() {
+    await shell(STOP_GATEWAY_UNITS).catch(() => { });
+    await shell(KILL_GATEWAY_BY_PORT).catch(() => { });
+}
+// `active 但端口未监听` 的最长等待:覆盖 restart 后进程已 active、端口还没
+// bind 的启动窗口。等满仍未监听就判 starting(配置异常 / 卡住),不再傻等。
+const STATUS_PORT_WAIT_ATTEMPTS = 20;
+async function isPortListening() {
+    const r = await shellCapture(`ss -ltnH 'sport = :${OPENCLAW_GATEWAY_PORT}' 2>/dev/null || true`);
+    return r.stdout.trim().length > 0;
+}
+async function isServiceActive() {
+    const r = await shellCapture(`${SYSTEMD_ENV}systemctl --user is-active openclaw-gateway.service 2>/dev/null || true`);
+    return r.stdout.trim() === 'active';
+}
+/**
+ * 探测 gateway 状态。**健康的唯一标准是 18789 端口已监听** —— 进程 active
+ * 不等于对外可服务。
+ *
+ * - `listening`:端口已监听,健康。
+ * - `starting` :systemd 服务 active,但端口在 bounded wait 内始终没监听 ——
+ *   配置异常 / 启动卡住 / 仍在初始化,**不算健康**。
+ * - `down`     :systemd 服务非 active 且端口未监听。
+ *
+ * `openclaw gateway restart` 返回后服务立刻是 active,但 gateway 进程还要几秒
+ * 才 bind 端口。所以端口没起来、服务却 active 时给一段 bounded wait 覆盖这个
+ * 启动窗口;服务都不 active 则直接 `down`,不等。
+ */
+export async function probeGatewayState() {
+    if (await isPortListening())
+        return 'listening';
+    if (!(await isServiceActive()))
+        return 'down';
+    for (let i = 0; i < STATUS_PORT_WAIT_ATTEMPTS; i++) {
+        await new Promise((resolve) => setTimeout(resolve, 1000));
+        if (await isPortListening())
+            return 'listening';
+    }
+    return 'starting';
+}
+/**
+ * 清掉 systemd user 目录下的 gateway unit 残留。`openclaw gateway uninstall`
+ * 只删主 `.service` 文件,残留的 `.service.bak` 备份和 `.service.d/` drop-in
+ * 会在下次 install 时被 systemd 自动 merge 进来(注入过时的 env 等),必须一并清。
+ */
+export async function cleanupGatewayServiceFiles() {
+    await shell(`${SYSTEMD_ENV}rm -rf /root/.config/systemd/user/openclaw-gateway.service.d` +
+        ` /root/.config/systemd/user/openclaw-gateway.service.bak;` +
+        ` systemctl --user daemon-reload 2>/dev/null || true`).catch(() => { });
+}
+/**
+ * Best-effort stop of the openclaw gateway so cli operations have exclusive
+ * write access to openclaw.json + extensions/.
+ *
+ * Why this is needed: the gateway has a config file watcher that writes its
+ * own metadata back into openclaw.json on every config change. Concurrent
+ * writes during cli's cleanup / `openclaw plugins install` / `openclaw config
+ * set` race with that watcher and produce:
+ *   - ENOTEMPTY: rmdir '.../node_modules/.cache/jiti' (jiti cache write race)
+ *   - ConfigMutationConflictError: config changed since last load (hash check
+ *     in openclaw plugins install commit / openclaw config set atomic write)
+ *
+ * Bootstrap orchestrator (commands/install.ts) is responsible for restarting
+ * the gateway after the full component install pipeline finishes.
+ *
+ * @param context A short label for logs, e.g. "dingtalk install" or
+ *                "openclaw deployment defaults".
+ */
+export async function stopDaemonForExclusiveAccess(context) {
+    info(`Stopping openclaw gateway for exclusive access during ${context}...`);
+    await stopGateway();
+    // `systemctl stop` 是显式停,Restart=always 不会把它拉回来;留 1.5s 兜底观察。
+    await new Promise((resolve) => setTimeout(resolve, 1500));
+}
+//# sourceMappingURL=openclaw-daemon.js.map

package/dist/utils/openclaw-daemon.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"openclaw-daemon.js","sourceRoot":"","sources":["../../src/utils/openclaw-daemon.ts"],"names":[],"mappings":"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"}

package/dist/utils/shell.d.ts

@@ -3,22 +3,43 @@ export interface ShellResult {
     stdout: string;
     stderr: string;
 }
+export interface CommandOptions {
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+}
 /**
  * Ensure running as root. If not, re-exec with sudo and exit.
  */
 export declare function ensureRoot(): void;
 /**
- * Run a shell command with inherited stdio (visible output).
- * Automatically sources nvm so node/npm/openclaw are available.
+ * Run a shell command and wait for exit.
+ *
+ * text 模式：stdio:inherit，子进程输出直通父进程 TTY（本地交互体验不变）。
+ *
+ * ndjson 模式：捕获 stdout/stderr 并按行合成 phase="log" 事件（stdout→level=info，
+ *   stderr→level=warn），通过 {@link getActiveEmitter} 拿到当前 op 的 emitter 发出。
+ *   这样像 `npm install` 这种几分钟才回一行 ndjson 的长操作，其实时进度也能通过
+ *   事件流推给 os-api / 前端，用户不会看到 UI 卡死 10 分钟。
+ *
+ *   透传是"尽力而为"：emitter 缺失（理论上只有本地脚本直接 import shell() 且没走
+ *   正常 command 入口才会发生）时静默吞，不影响命令本身执行。
+ *
  * Throws on non-zero exit.
  */
 export declare function shell(cmd: string): Promise<void>;
+/**
+ * Run a command with argv instead of interpolating external values into a shell
+ * string. The fixed bash wrapper only initializes nvm, then `exec "$@"`.
+ */
+export declare function runCommand(cmd: string, args?: string[], options?: CommandOptions): Promise<void>;
 /**
  * Run a shell command with retries.
  */
 export declare function shellRetry(cmd: string, retries?: number, delayMs?: number): Promise<void>;
+export declare function runCommandRetry(cmd: string, args?: string[], retries?: number, delayMs?: number, options?: CommandOptions): Promise<void>;
 /**
  * Run a shell command and capture stdout/stderr.
  */
 export declare function shellCapture(cmd: string): Promise<ShellResult>;
+export declare function runCommandCapture(cmd: string, args?: string[], options?: CommandOptions): Promise<ShellResult>;
 export declare function commandExists(cmd: string): Promise<boolean>;