@xfxstudio/claworld 0.1.0

package/src/openclaw/installer/cli.js

@@ -0,0 +1,349 @@
+import os from 'os';
+import path from 'path';
+import {
+  DEFAULT_CLAWORLD_TOOL_PROFILE,
+  expandUserPath,
+  normalizeClaworldToolProfile,
+} from '../plugin/managed-config.js';
+import {
+  CLAWORLD_DOCTOR_COMMAND,
+  CLAWORLD_INSTALLER_BIN_NAME,
+  CLAWORLD_INSTALLER_COMMAND,
+  CLAWORLD_INSTALLER_PACKAGE_NAME,
+  CLAWORLD_UPDATE_COMMAND,
+} from './constants.js';
+import { formatClaworldDoctorReport, runClaworldDoctor } from './doctor.js';
+import {
+  DEFAULT_OPENCLAW_BIN,
+  DEFAULT_OPENCLAW_CONFIG_PATH,
+  runClaworldInstallerInstall,
+  runClaworldInstallerUpdate,
+} from './core.js';
+
+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
+  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>             Managed local OpenClaw agent id (default: claworld)
+  --workspace <path>          Managed agent workspace path
+  --display-name <name>       Managed display name override
+  --tool-profile <name>       minimal | default | full (default: ${DEFAULT_CLAWORLD_TOOL_PROFILE})
+  --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_PACKAGE_NAME})
+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>             Managed local OpenClaw agent id (default: claworld)
+  --workspace <path>          Managed agent workspace path
+  --display-name <name>       Managed display name override
+  --tool-profile <name>       minimal | default | full (default: ${DEFAULT_CLAWORLD_TOOL_PROFILE})
+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>             Managed local OpenClaw agent id (default: claworld)
+  --workspace <path>          Managed workspace path override
+  --json                      Print machine-readable result
+  --help, -h                  Show this help
+
+Canonical commands:
+  ${CLAWORLD_INSTALLER_COMMAND}
+  ${CLAWORLD_DOCTOR_COMMAND}
+  ${CLAWORLD_UPDATE_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 = os.homedir();
+  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: 'claworld',
+      workspace: null,
+      displayName: null,
+      toolProfile: DEFAULT_CLAWORLD_TOOL_PROFILE,
+      repoRoot: null,
+      pluginInstallMode: 'npm',
+      pluginInstallSource: CLAWORLD_INSTALLER_PACKAGE_NAME,
+    },
+    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: 'claworld',
+      workspace: null,
+      displayName: null,
+      toolProfile: DEFAULT_CLAWORLD_TOOL_PROFILE,
+    },
+    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: 'claworld',
+      workspace: null,
+    },
+  };
+
+  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;
+        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;
+        index += 1;
+        break;
+      case '--openclaw-bin':
+        options.install.openclawBin = nextValue(remaining, index);
+        options.update.openclawBin = options.install.openclawBin;
+        options.doctor.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;
+        index += 1;
+        break;
+      case '--agent-id':
+        options.install.agentId = nextValue(remaining, index);
+        options.update.agentId = options.install.agentId;
+        options.doctor.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 = normalizeClaworldToolProfile(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);
+        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', '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_PACKAGE_NAME
+  ) {
+    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_PACKAGE_NAME
+  ) {
+    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_PACKAGE_NAME
+  ) {
+    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(`Canonical agentId:  ${result.activation?.agentId || '(unknown)'}`);
+  console.log(`OpenClaw version:   ${result.host?.version || '(unknown)'}`);
+  console.log(`Plugin action:      ${result.plugin?.action || 'unknown'}`);
+  console.log(`Activation mode:    ${result.activationMode}`);
+  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(`Canonical agentId:  ${result.activation?.agentId || '(unknown)'}`);
+  console.log(`OpenClaw version:   ${result.host?.version || '(unknown)'}`);
+  console.log(`Plugin action:      ${result.plugin?.action || 'unknown'}`);
+  console.log(`Tracked install:    ${trackedSummary}`);
+  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('');
+}
+
+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,
+    };
+  }
+
+  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,6 @@
+export const CLAWORLD_INSTALLER_BIN_NAME = 'claworld';
+export const CLAWORLD_INSTALLER_PACKAGE_NAME = '@xfxstudio/claworld';
+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_OPENCLAW_MIN_HOST_VERSION = '>=2026.3.14';