@xfxstudio/claworld 2026.4.16-testing.1 → 2026.4.16-testing.2

package/src/openclaw/plugin/onboarding.js

@@ -0,0 +1,312 @@
+import {
+  DEFAULT_CLAWORLD_ACCOUNT_ID,
+  applyClaworldManagedRuntimeConfig,
+  ensureObject,
+  normalizeText,
+  resolveClaworldManagedRuntimeOptions,
+} from './managed-config.js';
+import {
+  defaultClaworldAccountId,
+  inspectClaworldChannelAccount,
+  listClaworldAccountIds,
+} from './config-schema.js';
+
+function collectUnsupportedSetupFlags(input = {}) {
+  const unsupported = [];
+  const flagMap = [
+    ['appToken', '--app-token'],
+    ['token', '--token'],
+    ['tokenFile', '--token-file'],
+    ['botToken', '--bot-token'],
+    ['signalNumber', '--signal-number'],
+    ['cliPath', '--cli-path'],
+    ['dbPath', '--db-path'],
+    ['service', '--service'],
+    ['region', '--region'],
+    ['authDir', '--auth-dir'],
+    ['httpHost', '--http-host'],
+    ['httpPort', '--http-port'],
+    ['webhookPath', '--webhook-path'],
+    ['webhookUrl', '--webhook-url'],
+    ['audienceType', '--audience-type'],
+    ['audience', '--audience'],
+    ['homeserver', '--homeserver'],
+    ['userId', '--user-id'],
+    ['accessToken', '--access-token'],
+    ['password', '--password'],
+    ['deviceName', '--device-name'],
+    ['initialSyncLimit', '--initial-sync-limit'],
+    ['ship', '--ship'],
+  ];
+
+  for (const [field, flag] of flagMap) {
+    if (normalizeText(input[field], null)) unsupported.push(flag);
+  }
+  if (Array.isArray(input.groupChannels) && input.groupChannels.length > 0) unsupported.push('--group-channels');
+  if (Array.isArray(input.dmAllowlist) && input.dmAllowlist.length > 0) unsupported.push('--dm-allowlist');
+  if (input.autoDiscoverChannels === true) unsupported.push('--auto-discover-channels');
+  if (input.useEnv === true) unsupported.push('--use-env');
+  return unsupported;
+}
+
+export function validateClaworldSetupInput({ input = {} } = {}) {
+  const unsupportedFlags = collectUnsupportedSetupFlags(input);
+  if (unsupportedFlags.length > 0) {
+    return (
+      'Claworld host-native setup only supports an optional local account label and --http-url/--url overrides. '
+      + `Unsupported flag(s): ${unsupportedFlags.join(', ')}.`
+    );
+  }
+
+  const serverUrl = normalizeText(input.httpUrl, normalizeText(input.url, null));
+  if (!serverUrl) {
+    return null;
+  }
+
+  try {
+    const parsed = new URL(serverUrl);
+    if (!['http:', 'https:', 'ws:', 'wss:'].includes(parsed.protocol)) {
+      return `Unsupported Claworld server URL protocol: ${parsed.protocol}`;
+    }
+  } catch {
+    return `Invalid Claworld server URL: ${serverUrl}`;
+  }
+
+  return null;
+}
+
+function findAgentEntry(config = {}, agentId) {
+  const normalizedAgentId = normalizeText(agentId, null);
+  if (!normalizedAgentId) return null;
+  const list = Array.isArray(config?.agents?.list) ? config.agents.list : [];
+  return list
+    .map((entry) => ensureObject(entry))
+    .find((entry) => entry.id === normalizedAgentId) || null;
+}
+
+function hasClaworldBinding(config = {}, { agentId, accountId } = {}) {
+  const normalizedAgentId = normalizeText(agentId, null);
+  const normalizedAccountId = normalizeText(accountId, DEFAULT_CLAWORLD_ACCOUNT_ID);
+  const resolvedDefaultAccountId = defaultClaworldAccountId(config) || DEFAULT_CLAWORLD_ACCOUNT_ID;
+  const bindings = Array.isArray(config?.bindings) ? config.bindings : [];
+  return bindings.some((binding) => {
+    const candidate = ensureObject(binding);
+    const match = ensureObject(candidate.match);
+    const bindingChannel = normalizeText(match.channel, null);
+    const bindingAccountId = normalizeText(match.accountId, null);
+    const bindingAgentId = normalizeText(candidate.agentId, null);
+    if (bindingChannel !== 'claworld') return false;
+    if (normalizedAgentId && bindingAgentId !== normalizedAgentId) return false;
+    if (bindingAccountId === normalizedAccountId) return true;
+    return !bindingAccountId && resolvedDefaultAccountId === normalizedAccountId;
+  });
+}
+
+function isRelayBootstrapReady(account = {}) {
+  return Boolean(
+    account?.configured
+    && normalizeText(account?.appToken, null),
+  );
+}
+
+export function inspectManagedClaworldInstall({
+  cfg = {},
+  accountId = DEFAULT_CLAWORLD_ACCOUNT_ID,
+  input = {},
+  overrides = {},
+} = {}) {
+  const configuredAccountIds = listClaworldAccountIds(cfg);
+  const hasAnyConfig = configuredAccountIds.length > 0 || cfg?.channels?.claworld != null;
+  const managedOptions = resolveClaworldManagedRuntimeOptions({
+    cfg,
+    accountId,
+    input,
+    overrides,
+  });
+  const managedAgentPresent = Boolean(findAgentEntry(cfg, managedOptions.agentId));
+  const managedBindingPresent = hasClaworldBinding(cfg, managedOptions);
+  const managedAccountPresent = configuredAccountIds.includes(managedOptions.accountId);
+  const accountStatus = managedAccountPresent
+    ? inspectClaworldChannelAccount(cfg, managedOptions.accountId)
+    : inspectClaworldChannelAccount({}, managedOptions.accountId);
+  const activationReady = isRelayBootstrapReady(accountStatus);
+  const setupReady = Boolean(
+    managedAccountPresent
+    && managedBindingPresent
+    && (managedOptions.manageAgentEntry !== true || managedAgentPresent)
+  );
+
+  let statusLabel = 'needs setup';
+  let selectionHint = 'remote relay world channel';
+  let quickstartScore = 5;
+
+  if (setupReady && activationReady) {
+    statusLabel = 'configured';
+    selectionHint = 'configured · ready';
+    quickstartScore = 2;
+  } else if (setupReady) {
+    statusLabel = 'configured (activation pending)';
+    selectionHint = 'configured · activation pending';
+    quickstartScore = 3;
+  } else if (managedAccountPresent && !managedBindingPresent) {
+    statusLabel = 'configured (binding pending)';
+    selectionHint = 'configured · binding pending';
+    quickstartScore = 4;
+  } else if (hasAnyConfig) {
+    statusLabel = 'configured (refresh recommended)';
+    selectionHint = 'configured · refresh recommended';
+    quickstartScore = 4;
+  }
+
+  return {
+    hasAnyConfig,
+    configuredAccountIds,
+    defaultAccountId: defaultClaworldAccountId(cfg) || null,
+    managedOptions,
+    managedAccountPresent,
+    managedAgentPresent,
+    managedBindingPresent,
+    accountStatus,
+    activationReady,
+    setupReady,
+    statusLabel,
+    selectionHint,
+    quickstartScore,
+  };
+}
+
+export function buildClaworldOnboardingStatus({
+  cfg = {},
+  accountId = DEFAULT_CLAWORLD_ACCOUNT_ID,
+} = {}) {
+  const inspection = inspectManagedClaworldInstall({ cfg, accountId });
+  return {
+    configured: inspection.setupReady,
+    statusLines: [`Claworld: ${inspection.statusLabel}`],
+    selectionHint: inspection.selectionHint,
+    quickstartScore: inspection.quickstartScore,
+    activationReady: inspection.activationReady,
+  };
+}
+
+function applyManagedAccountName({ cfg = {}, accountId, name } = {}) {
+  const normalizedName = normalizeText(name, null);
+  if (!normalizedName) return cfg;
+
+  const next = JSON.parse(JSON.stringify(ensureObject(cfg)));
+  next.channels = ensureObject(next.channels);
+  const claworldRoot = ensureObject(next.channels.claworld);
+  const accounts = ensureObject(claworldRoot.accounts);
+  const existingAccount = ensureObject(accounts[accountId]);
+  accounts[accountId] = {
+    ...existingAccount,
+    name: normalizedName,
+    ...(existingAccount.registration
+      ? {
+          registration: {
+            ...ensureObject(existingAccount.registration),
+            displayName: normalizedName,
+          },
+        }
+      : {}),
+  };
+  next.channels.claworld = {
+    ...claworldRoot,
+    accounts,
+  };
+  return next;
+}
+
+function resolveManagedOptionsFromContext({ cfg = {}, accountId = null, input = {}, overrides = {} } = {}) {
+  const normalizedInput = ensureObject(input);
+  const resolvedInput = { ...normalizedInput };
+  delete resolvedInput.name;
+  return resolveClaworldManagedRuntimeOptions({
+    cfg,
+    accountId: normalizeText(accountId, DEFAULT_CLAWORLD_ACCOUNT_ID),
+    input: resolvedInput,
+    overrides: {
+      ...overrides,
+      ...(normalizeText(normalizedInput.name, null) ? { name: normalizedInput.name } : {}),
+    },
+  });
+}
+
+async function applyManagedOnboardingConfig({
+  cfg = {},
+  prompter,
+  accountId = null,
+  phase = 'setup',
+  input = {},
+} = {}) {
+  const managedOptions = resolveManagedOptionsFromContext({ cfg, accountId, input });
+  const next = applyClaworldManagedRuntimeConfig(cfg, managedOptions);
+
+  const noteLines = [
+    `Bound local agent/account: ${managedOptions.agentId}`,
+    `Remote backend: ${managedOptions.serverUrl}`,
+    managedOptions.appToken
+      ? 'Activation state: ready via configured appToken'
+      : 'Activation state: pending until claworld_account(action=update_identity) runs',
+    'This flow refreshes plugin-side config and binds claworld onto the selected local agent. It does not run installer commands or start a backend service.',
+  ];
+  await prompter.note(
+    noteLines.join('\n'),
+    phase === 'refresh' ? 'Claworld refresh' : 'Claworld setup',
+  );
+
+  return {
+    cfg: next.config,
+    accountId: managedOptions.accountId,
+  };
+}
+
+export const claworldSetupAdapter = {
+  resolveAccountId: ({ accountId }) => normalizeText(accountId, DEFAULT_CLAWORLD_ACCOUNT_ID),
+  resolveBindingAccountId: ({ cfg, agentId, accountId }) => {
+    const explicit = normalizeText(accountId, null);
+    if (explicit) return explicit;
+    const normalizedAgentId = normalizeText(agentId, null);
+    const accountIds = listClaworldAccountIds(cfg);
+    if (normalizedAgentId && accountIds.includes(normalizedAgentId)) {
+      return normalizedAgentId;
+    }
+    return accountIds.length > 0 ? defaultClaworldAccountId(cfg) : DEFAULT_CLAWORLD_ACCOUNT_ID;
+  },
+  applyAccountName: ({ cfg, accountId, name }) => applyManagedAccountName({ cfg, accountId, name }),
+  validateInput: ({ input }) => validateClaworldSetupInput({ input }),
+  applyAccountConfig: ({ cfg, accountId, input }) => {
+    const managedOptions = resolveManagedOptionsFromContext({ cfg, accountId, input });
+    return applyClaworldManagedRuntimeConfig(cfg, managedOptions).config;
+  },
+};
+
+export const claworldOnboardingAdapter = {
+  channel: 'claworld',
+  getStatus: async ({ cfg, accountOverrides }) => {
+    const managedAccountId = normalizeText(accountOverrides?.claworld, DEFAULT_CLAWORLD_ACCOUNT_ID);
+    return {
+      channel: 'claworld',
+      ...buildClaworldOnboardingStatus({
+        cfg,
+        accountId: managedAccountId,
+      }),
+    };
+  },
+  configure: async ({ cfg, prompter, accountOverrides }) =>
+    applyManagedOnboardingConfig({
+      cfg,
+      prompter,
+      accountId: accountOverrides?.claworld,
+      phase: 'setup',
+      input: {},
+    }),
+  configureWhenConfigured: async ({ cfg, prompter, accountOverrides }) =>
+    applyManagedOnboardingConfig({
+      cfg,
+      prompter,
+      accountId: accountOverrides?.claworld,
+      phase: 'refresh',
+      input: {},
+    }),
+};