@xfxstudio/claworld 0.2.15 → 0.2.16

package/src/openclaw/installer/cli.js

@@ -0,0 +1,406 @@
+import os from 'os';
+import path from 'path';
+import {
+  expandUserPath,
+} from '../plugin/managed-config.js';
+import {
+  CLAWORLD_DOCTOR_COMMAND,
+  CLAWORLD_INSTALLER_BIN_NAME,
+  CLAWORLD_INSTALLER_COMMAND,
+  CLAWORLD_INSTALLER_DEFAULT_PLUGIN_SOURCE,
+  CLAWORLD_UNINSTALL_COMMAND,
+  CLAWORLD_UPDATE_COMMAND,
+} from './constants.js';
+import { formatClaworldDoctorReport, runClaworldDoctor } from './doctor.js';
+import {
+  DEFAULT_OPENCLAW_BIN,
+  DEFAULT_OPENCLAW_CONFIG_PATH,
+  runClaworldInstallerInstall,
+  runClaworldInstallerUninstall,
+  runClaworldInstallerUpdate,
+} from './core.js';
+
+function resolveCliHomeDir(env = process.env) {
+  const envHomeDir = String(
+    env.HOME
+    || env.USERPROFILE
+    || (
+      env.HOMEDRIVE && env.HOMEPATH
+        ? path.join(env.HOMEDRIVE, env.HOMEPATH)
+        : ''
+    ),
+  ).trim();
+  return envHomeDir || os.homedir();
+}
+
+function printHelp() {
+  console.log(`Usage: ${CLAWORLD_INSTALLER_BIN_NAME} <command> [options]
+
+Commands:
+  install                     Run the installer-first Claworld setup flow
+  doctor                      Validate the managed Claworld install health
+  update                      Update the tracked Claworld plugin, refresh managed state, and run doctor
+  uninstall                   Safely remove the managed Claworld runtime and uninstall the plugin
+  upgrade                     Alias for update
+  help                        Show this help
+
+Install options:
+  --config <path>             OpenClaw config path (default: ${DEFAULT_OPENCLAW_CONFIG_PATH})
+  --state-dir <path>          Optional OPENCLAW_STATE_DIR for OpenClaw commands
+  --openclaw-bin <path>       OpenClaw CLI binary (default: ${DEFAULT_OPENCLAW_BIN})
+  --server-url <url>          Override the Claworld backend URL
+  --api-key <value>           Override the Claworld backend API key
+  --account-id <id>           Managed Claworld account id (default: claworld)
+  --agent-id <id>             Local OpenClaw agent id to bind claworld onto (default: main)
+  --workspace <path>          Optional dedicated workspace path for claworld-specific bootstrap files
+  --display-name <name>       Managed display name override
+  --tool-profile <profile>    minimal | default | full | world
+  --repo-root <path>          Local repo root when using --plugin-install-mode link|copy
+  --plugin-install-mode <m>   npm | link | copy | skip (default: npm)
+  --plugin-source <value>     npm package or local path (default: ${CLAWORLD_INSTALLER_DEFAULT_PLUGIN_SOURCE})
+Update options:
+  --config <path>             OpenClaw config path (default: ${DEFAULT_OPENCLAW_CONFIG_PATH})
+  --state-dir <path>          Optional OPENCLAW_STATE_DIR for OpenClaw commands
+  --openclaw-bin <path>       OpenClaw CLI binary (default: ${DEFAULT_OPENCLAW_BIN})
+  --server-url <url>          Override the Claworld backend URL
+  --api-key <value>           Override the Claworld backend API key
+  --account-id <id>           Managed Claworld account id (default: claworld)
+  --agent-id <id>             Local OpenClaw agent id bound to claworld (default: main)
+  --workspace <path>          Optional dedicated workspace path for claworld-specific bootstrap files
+  --display-name <name>       Managed display name override
+  --tool-profile <profile>    minimal | default | full | world
+Doctor options:
+  --config <path>             OpenClaw config path (default: ${DEFAULT_OPENCLAW_CONFIG_PATH})
+  --state-dir <path>          Optional OPENCLAW_STATE_DIR for OpenClaw commands
+  --openclaw-bin <path>       OpenClaw CLI binary (default: ${DEFAULT_OPENCLAW_BIN})
+  --server-url <url>          Override the Claworld backend URL
+  --account-id <id>           Managed Claworld account id (default: claworld)
+  --agent-id <id>             Local OpenClaw agent id bound to claworld (default: main)
+  --workspace <path>          Optional dedicated workspace path override
+Uninstall options:
+  --config <path>             OpenClaw config path (default: ${DEFAULT_OPENCLAW_CONFIG_PATH})
+  --state-dir <path>          Optional OPENCLAW_STATE_DIR for OpenClaw commands
+  --openclaw-bin <path>       OpenClaw CLI binary (default: ${DEFAULT_OPENCLAW_BIN})
+  --account-id <id>           Managed Claworld account id (default: claworld)
+  --agent-id <id>             Local OpenClaw agent id bound to claworld (default: main)
+  --json                      Print machine-readable result
+  --help, -h                  Show this help
+
+Canonical commands:
+  ${CLAWORLD_INSTALLER_COMMAND}
+  ${CLAWORLD_DOCTOR_COMMAND}
+  ${CLAWORLD_UPDATE_COMMAND}
+  ${CLAWORLD_UNINSTALL_COMMAND}
+`);
+}
+
+function nextValue(argv, index) {
+  if (index + 1 >= argv.length) {
+    throw new Error(`Missing value for ${argv[index]}`);
+  }
+  return argv[index + 1];
+}
+
+export function parseInstallerCliArgs(argv = process.argv.slice(2), env = process.env) {
+  const homeDir = resolveCliHomeDir(env);
+  const options = {
+    command: null,
+    json: false,
+    install: {
+      openclawBin: env.OPENCLAW_BIN || DEFAULT_OPENCLAW_BIN,
+      configPath: expandUserPath(env.OPENCLAW_CONFIG_PATH || DEFAULT_OPENCLAW_CONFIG_PATH, homeDir),
+      stateDir: env.OPENCLAW_STATE_DIR ? expandUserPath(env.OPENCLAW_STATE_DIR, homeDir) : null,
+      serverUrl: null,
+      apiKey: null,
+      accountId: 'claworld',
+      agentId: 'main',
+      workspace: null,
+      displayName: null,
+      repoRoot: null,
+      pluginInstallMode: 'npm',
+      pluginInstallSource: CLAWORLD_INSTALLER_DEFAULT_PLUGIN_SOURCE,
+      toolProfile: null,
+    },
+    update: {
+      openclawBin: env.OPENCLAW_BIN || DEFAULT_OPENCLAW_BIN,
+      configPath: expandUserPath(env.OPENCLAW_CONFIG_PATH || DEFAULT_OPENCLAW_CONFIG_PATH, homeDir),
+      stateDir: env.OPENCLAW_STATE_DIR ? expandUserPath(env.OPENCLAW_STATE_DIR, homeDir) : null,
+      serverUrl: null,
+      apiKey: null,
+      accountId: 'claworld',
+      agentId: 'main',
+      workspace: null,
+      displayName: null,
+      pluginInstallSource: CLAWORLD_INSTALLER_DEFAULT_PLUGIN_SOURCE,
+      toolProfile: null,
+    },
+    doctor: {
+      openclawBin: env.OPENCLAW_BIN || DEFAULT_OPENCLAW_BIN,
+      configPath: expandUserPath(env.OPENCLAW_CONFIG_PATH || DEFAULT_OPENCLAW_CONFIG_PATH, homeDir),
+      stateDir: env.OPENCLAW_STATE_DIR ? expandUserPath(env.OPENCLAW_STATE_DIR, homeDir) : null,
+      serverUrl: null,
+      accountId: 'claworld',
+      agentId: 'main',
+      workspace: null,
+    },
+    uninstall: {
+      openclawBin: env.OPENCLAW_BIN || DEFAULT_OPENCLAW_BIN,
+      configPath: expandUserPath(env.OPENCLAW_CONFIG_PATH || DEFAULT_OPENCLAW_CONFIG_PATH, homeDir),
+      stateDir: env.OPENCLAW_STATE_DIR ? expandUserPath(env.OPENCLAW_STATE_DIR, homeDir) : null,
+      accountId: 'claworld',
+      agentId: 'main',
+    },
+  };
+
+  if (argv.length === 0) {
+    printHelp();
+    return { ...options, command: 'help' };
+  }
+
+  options.command = argv[0] === 'upgrade' ? 'update' : argv[0];
+  const remaining = argv.slice(1);
+
+  for (let index = 0; index < remaining.length; index += 1) {
+    const arg = remaining[index];
+    switch (arg) {
+      case '--config':
+        options.install.configPath = expandUserPath(nextValue(remaining, index), homeDir);
+        options.update.configPath = options.install.configPath;
+        options.doctor.configPath = options.install.configPath;
+        options.uninstall.configPath = options.install.configPath;
+        index += 1;
+        break;
+      case '--state-dir':
+        options.install.stateDir = expandUserPath(nextValue(remaining, index), homeDir);
+        options.update.stateDir = options.install.stateDir;
+        options.doctor.stateDir = options.install.stateDir;
+        options.uninstall.stateDir = options.install.stateDir;
+        index += 1;
+        break;
+      case '--openclaw-bin':
+        options.install.openclawBin = nextValue(remaining, index);
+        options.update.openclawBin = options.install.openclawBin;
+        options.doctor.openclawBin = options.install.openclawBin;
+        options.uninstall.openclawBin = options.install.openclawBin;
+        index += 1;
+        break;
+      case '--server-url':
+        options.install.serverUrl = nextValue(remaining, index);
+        options.update.serverUrl = options.install.serverUrl;
+        options.doctor.serverUrl = options.install.serverUrl;
+        index += 1;
+        break;
+      case '--api-key':
+        options.install.apiKey = nextValue(remaining, index);
+        options.update.apiKey = options.install.apiKey;
+        index += 1;
+        break;
+      case '--account-id':
+        options.install.accountId = nextValue(remaining, index);
+        options.update.accountId = options.install.accountId;
+        options.doctor.accountId = options.install.accountId;
+        options.uninstall.accountId = options.install.accountId;
+        index += 1;
+        break;
+      case '--agent-id':
+        options.install.agentId = nextValue(remaining, index);
+        options.update.agentId = options.install.agentId;
+        options.doctor.agentId = options.install.agentId;
+        options.uninstall.agentId = options.install.agentId;
+        index += 1;
+        break;
+      case '--workspace':
+        options.install.workspace = expandUserPath(nextValue(remaining, index), homeDir);
+        options.update.workspace = options.install.workspace;
+        options.doctor.workspace = options.install.workspace;
+        index += 1;
+        break;
+      case '--display-name':
+        options.install.displayName = nextValue(remaining, index);
+        options.update.displayName = options.install.displayName;
+        index += 1;
+        break;
+      case '--tool-profile':
+        options.install.toolProfile = nextValue(remaining, index);
+        options.update.toolProfile = options.install.toolProfile;
+        index += 1;
+        break;
+      case '--repo-root':
+        options.install.repoRoot = path.resolve(expandUserPath(nextValue(remaining, index), homeDir));
+        index += 1;
+        break;
+      case '--plugin-install-mode':
+        options.install.pluginInstallMode = nextValue(remaining, index);
+        index += 1;
+        break;
+      case '--plugin-source':
+        options.install.pluginInstallSource = nextValue(remaining, index);
+        options.update.pluginInstallSource = options.install.pluginInstallSource;
+        index += 1;
+        break;
+      case '--json':
+        options.json = true;
+        break;
+      case '--help':
+      case '-h':
+        printHelp();
+        return { ...options, command: 'help' };
+      default:
+        throw new Error(`Unknown argument: ${arg}`);
+    }
+  }
+
+  if (!['install', 'update', 'uninstall', 'doctor', 'help'].includes(options.command)) {
+    throw new Error(`Unknown command: ${options.command}`);
+  }
+  if (options.command === 'install' && !['npm', 'link', 'copy', 'skip'].includes(options.install.pluginInstallMode)) {
+    throw new Error(`Unsupported plugin install mode: ${options.install.pluginInstallMode}`);
+  }
+  if (
+    options.command === 'install'
+    && options.install.pluginInstallMode !== 'npm'
+    && !options.install.repoRoot
+    && !options.install.pluginInstallSource
+  ) {
+    throw new Error('Local plugin install mode requires --repo-root or --plugin-source.');
+  }
+  if (
+    options.command === 'install'
+    && options.install.pluginInstallMode === 'link'
+    && !options.install.repoRoot
+    && options.install.pluginInstallSource === CLAWORLD_INSTALLER_DEFAULT_PLUGIN_SOURCE
+  ) {
+    throw new Error('Link install mode requires --repo-root or --plugin-source <local-path>.');
+  }
+  if (
+    options.command === 'install'
+    && options.install.pluginInstallMode === 'copy'
+    && !options.install.repoRoot
+    && options.install.pluginInstallSource === CLAWORLD_INSTALLER_DEFAULT_PLUGIN_SOURCE
+  ) {
+    throw new Error('Copy install mode requires --repo-root or --plugin-source <local-path>.');
+  }
+
+  if (
+    options.command === 'install'
+    && options.install.pluginInstallMode !== 'npm'
+    && options.install.repoRoot
+    && options.install.pluginInstallSource === CLAWORLD_INSTALLER_DEFAULT_PLUGIN_SOURCE
+  ) {
+    options.install.pluginInstallSource = options.install.repoRoot;
+  }
+
+  return options;
+}
+
+function printInstallSummary(result) {
+  console.log('');
+  console.log('Claworld installer complete');
+  console.log('===========================');
+  console.log(`Managed account:    ${result.transformed?.config?.channels?.claworld?.defaultAccount || 'claworld'}`);
+  console.log(`OpenClaw version:   ${result.host?.version || '(unknown)'}`);
+  console.log(`Plugin action:      ${result.plugin?.action || 'unknown'}`);
+  console.log(`Activation:         ${result.activationStatus === 'ready' ? 'ready' : 'pending via claworld_account'}`);
+  console.log(`Runtime refresh:    ${result.runtimeRefresh?.action || 'unknown'}`);
+  console.log(`Config path:        ${result.configPath}`);
+  console.log(`Backup path:        ${result.backupPath || '(unchanged or new file)'}`);
+  console.log('');
+}
+
+function printUpdateSummary(result, doctorResult) {
+  const trackedInstall = result.plugin?.trackedInstall || null;
+  const trackedSummary = trackedInstall?.tracked
+    ? `${trackedInstall.source || 'tracked'}${trackedInstall.spec ? ` (${trackedInstall.spec})` : ''}`
+    : 'not recorded';
+  console.log('');
+  console.log('Claworld update complete');
+  console.log('========================');
+  console.log(`Managed account:    ${result.managedOptions?.accountId || 'claworld'}`);
+  console.log(`OpenClaw version:   ${result.host?.version || '(unknown)'}`);
+  console.log(`Plugin action:      ${result.plugin?.action || 'unknown'}`);
+  console.log(`Tracked install:    ${trackedSummary}`);
+  console.log(`Activation:         ${result.activationStatus === 'ready' ? 'ready' : 'pending via claworld_account'}`);
+  console.log(`Runtime refresh:    ${result.runtimeRefresh?.action || 'unknown'}`);
+  console.log(`Doctor status:      ${doctorResult?.status || 'unknown'}`);
+  console.log(`Config path:        ${result.configPath}`);
+  console.log(`Backup path:        ${result.backupPath || '(unchanged or new file)'}`);
+  console.log('');
+}
+
+function printUninstallSummary(result) {
+  console.log('');
+  console.log('Claworld uninstall complete');
+  console.log('===========================');
+  console.log(`Managed account:    ${result.transformed?.backup?.accountId || 'claworld'}`);
+  console.log(`OpenClaw version:   ${result.host?.version || '(unknown)'}`);
+  console.log(`Plugin action:      ${result.plugin?.action || 'unknown'}`);
+  console.log(`Runtime refresh:    ${result.runtimeRefresh?.action || 'unknown'}`);
+  console.log(`Config path:        ${result.configPath}`);
+  console.log(`Backup path:        ${result.backupPath || '(unchanged or new file)'}`);
+  console.log('');
+}
+
+export async function runInstallerCli(argv = process.argv.slice(2), env = process.env) {
+  const parsed = parseInstallerCliArgs(argv, env);
+  if (parsed.command === 'help') {
+    return { ok: true, command: 'help' };
+  }
+
+  if (parsed.command === 'install') {
+    const result = await runClaworldInstallerInstall(parsed.install);
+    if (parsed.json) {
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      printInstallSummary(result);
+    }
+    return result;
+  }
+
+  if (parsed.command === 'update') {
+    const result = await runClaworldInstallerUpdate(parsed.update);
+    const doctorResult = await runClaworldDoctor({
+      ...parsed.doctor,
+      configPath: result.configPath,
+      stateDir: result.stateDir,
+      serverUrl: result.effectiveServerUrl || parsed.doctor.serverUrl,
+      accountId: result.managedOptions?.accountId || parsed.doctor.accountId,
+      agentId: result.managedOptions?.agentId || parsed.doctor.agentId,
+      workspace: result.managedOptions?.workspace || parsed.doctor.workspace,
+    });
+    if (parsed.json) {
+      console.log(JSON.stringify({ ...result, doctor: doctorResult }, null, 2));
+    } else {
+      printUpdateSummary(result, doctorResult);
+      process.stdout.write(formatClaworldDoctorReport(doctorResult));
+    }
+    if (!doctorResult.ok) {
+      process.exitCode = 1;
+    }
+    return {
+      ...result,
+      doctor: doctorResult,
+      ok: doctorResult.ok,
+    };
+  }
+
+  if (parsed.command === 'uninstall') {
+    const result = await runClaworldInstallerUninstall(parsed.uninstall);
+    if (parsed.json) {
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      printUninstallSummary(result);
+    }
+    return result;
+  }
+
+  const result = await runClaworldDoctor(parsed.doctor);
+  if (parsed.json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    process.stdout.write(formatClaworldDoctorReport(result));
+  }
+  if (!result.ok) {
+    process.exitCode = 1;
+  }
+  return result;
+}

package/src/openclaw/installer/constants.js

@@ -0,0 +1,14 @@
+import { createRequire } from 'module';
+
+const require = createRequire(import.meta.url);
+const installerPackageJson = require('../../../package.json');
+
+export const CLAWORLD_INSTALLER_BIN_NAME = 'claworld';
+export const CLAWORLD_INSTALLER_PACKAGE_NAME = '@xfxstudio/claworld';
+export const CLAWORLD_INSTALLER_PACKAGE_VERSION = installerPackageJson.version;
+export const CLAWORLD_INSTALLER_DEFAULT_PLUGIN_SOURCE = `${CLAWORLD_INSTALLER_PACKAGE_NAME}@${CLAWORLD_INSTALLER_PACKAGE_VERSION}`;
+export const CLAWORLD_INSTALLER_COMMAND = 'npx -y @xfxstudio/claworld install';
+export const CLAWORLD_DOCTOR_COMMAND = 'npx -y @xfxstudio/claworld doctor';
+export const CLAWORLD_UPDATE_COMMAND = 'npx -y @xfxstudio/claworld update';
+export const CLAWORLD_UNINSTALL_COMMAND = 'npx -y @xfxstudio/claworld uninstall';
+export const CLAWORLD_OPENCLAW_MIN_HOST_VERSION = '>=2026.3.22';