@full-self-developing/fsd 1.0.0

package/extensions/codex/src/migration/apply.ts

@@ -0,0 +1,501 @@
+import path from "node:path";
+import {
+  applyMigrationManualItem,
+  markMigrationItemConflict,
+  markMigrationItemError,
+  markMigrationItemSkipped,
+  MIGRATION_REASON_TARGET_EXISTS,
+  summarizeMigrationItems,
+  writeMigrationConfigPath,
+} from "openclaw/plugin-sdk/migration";
+import {
+  archiveMigrationItem,
+  copyMigrationFileItem,
+  withCachedMigrationConfigRuntime,
+  writeMigrationReport,
+} from "openclaw/plugin-sdk/migration-runtime";
+import type {
+  MigrationApplyResult,
+  MigrationItem,
+  MigrationPlan,
+  MigrationProviderContext,
+} from "openclaw/plugin-sdk/plugin-entry";
+import { defaultCodexAppInventoryCache } from "../app-server/app-inventory-cache.js";
+import {
+  resolveCodexAppServerAuthAccountCacheKey,
+  resolveCodexAppServerAuthProfileIdForAgent,
+  resolveCodexAppServerEnvApiKeyCacheKey,
+} from "../app-server/auth-bridge.js";
+import {
+  CODEX_PLUGINS_MARKETPLACE_NAME,
+  readCodexPluginConfig,
+  resolveCodexAppServerRuntimeOptions,
+  type ResolvedCodexPluginPolicy,
+} from "../app-server/config.js";
+import {
+  ensureCodexPluginActivation,
+  type CodexPluginActivationResult,
+} from "../app-server/plugin-activation.js";
+import { buildCodexPluginAppCacheKey } from "../app-server/plugin-app-cache-key.js";
+import type { v2 } from "../app-server/protocol.js";
+import { requestCodexAppServerJson } from "../app-server/request.js";
+import {
+  clearSharedCodexAppServerClientIfCurrentAndWait,
+  getSharedCodexAppServerClient,
+} from "../app-server/shared-client.js";
+import { buildCodexMigrationPlan } from "./plan.js";
+import {
+  buildCodexPluginsConfigValue,
+  CODEX_PLUGIN_CONFIG_ITEM_ID,
+  CODEX_PLUGIN_CONFIG_PATH,
+  hasCodexPluginConfigConflict,
+  readCodexPluginMigrationConfigEntry,
+  type CodexPluginMigrationConfigEntry,
+} from "./plan.js";
+import { resolveCodexMigrationTargets } from "./targets.js";
+
+const CODEX_PLUGIN_AUTH_REQUIRED_REASON = "auth_required";
+const CODEX_PLUGIN_NOT_SELECTED_REASON = "not selected for migration";
+const CODEX_CONFIG_PATCH_MODE_RETURN = "return";
+const CODEX_PLUGIN_LOAD_WARNING =
+  "Some Codex plugins could not be migrated. Run `openclaw migrate codex` after onboarding.";
+const TARGET_CODEX_MARKETPLACE_DISCOVERY_POLL_MS = 250;
+const TARGET_CODEX_MARKETPLACE_DISCOVERY_TIMEOUT_MS = 30_000;
+const TARGET_CODEX_MARKETPLACE_DISCOVERY_TIMEOUT_ENV =
+  "OPENCLAW_CODEX_MIGRATION_PLUGIN_LIST_TIMEOUT_MS";
+
+export type CodexMigrationTargetAppServerPreparation = {
+  dispose: () => Promise<void>;
+};
+
+class CodexPluginConfigConflictError extends Error {
+  constructor(readonly reason: string) {
+    super(reason);
+    this.name = "CodexPluginConfigConflictError";
+  }
+}
+
+function shouldReturnCodexPluginConfigPatch(ctx: MigrationProviderContext): boolean {
+  return ctx.providerOptions?.configPatchMode === CODEX_CONFIG_PATCH_MODE_RETURN;
+}
+
+export function prepareTargetCodexAppServer(
+  ctx: MigrationProviderContext,
+): CodexMigrationTargetAppServerPreparation {
+  const appServer = resolveTargetCodexAppServer(ctx);
+  const targets = resolveCodexMigrationTargets(ctx);
+  let warmedClient: Awaited<ReturnType<typeof getSharedCodexAppServerClient>> | undefined;
+  const ready = getSharedCodexAppServerClient({
+    startOptions: appServer.start,
+    timeoutMs: 60_000,
+    agentDir: targets.agentDir,
+    config: ctx.config,
+  }).then(
+    (client) => {
+      warmedClient = client;
+    },
+    () => undefined,
+  );
+  return {
+    async dispose() {
+      await ready;
+      await clearSharedCodexAppServerClientIfCurrentAndWait(warmedClient, {
+        exitTimeoutMs: 2_000,
+        forceKillDelayMs: 250,
+      });
+    },
+  };
+}
+
+export async function applyCodexMigrationPlan(params: {
+  ctx: MigrationProviderContext;
+  plan?: MigrationPlan;
+  runtime?: MigrationProviderContext["runtime"];
+}): Promise<MigrationApplyResult> {
+  const plan = params.plan ?? (await buildCodexMigrationPlan(params.ctx));
+  const reportDir = params.ctx.reportDir ?? path.join(params.ctx.stateDir, "migration", "codex");
+  const items: MigrationItem[] = [];
+  const runtime = withCachedMigrationConfigRuntime(
+    params.ctx.runtime ?? params.runtime,
+    params.ctx.config,
+  );
+  const applyCtx = { ...params.ctx, runtime };
+  for (const item of plan.items) {
+    if (item.status !== "planned") {
+      items.push(item);
+      continue;
+    }
+    if (item.id === CODEX_PLUGIN_CONFIG_ITEM_ID) {
+      items.push(await applyCodexPluginConfigItem(applyCtx, item, items));
+    } else if (item.kind === "plugin" && item.action === "install") {
+      items.push(await applyCodexPluginInstallItem(applyCtx, item));
+    } else if (item.kind === "manual") {
+      items.push(applyMigrationManualItem(item));
+    } else if (item.action === "archive") {
+      items.push(await archiveMigrationItem(item, reportDir));
+    } else {
+      items.push(await copyMigrationFileItem(item, reportDir, { overwrite: params.ctx.overwrite }));
+    }
+  }
+  const result: MigrationApplyResult = {
+    ...plan,
+    items,
+    summary: summarizeMigrationItems(items),
+    backupPath: params.ctx.backupPath,
+    reportDir,
+  };
+  if (items.some(isCodexPluginLoadWarningItem)) {
+    result.warnings = [...new Set([...(result.warnings ?? []), CODEX_PLUGIN_LOAD_WARNING])];
+    result.nextSteps = [...new Set([CODEX_PLUGIN_LOAD_WARNING, ...(result.nextSteps ?? [])])];
+  }
+  await writeMigrationReport(result, { title: "Codex Migration Report" });
+  return result;
+}
+
+async function applyCodexPluginInstallItem(
+  ctx: MigrationProviderContext,
+  item: MigrationItem,
+): Promise<MigrationItem> {
+  const policy = readCodexPluginPolicy(item);
+  if (!policy) {
+    return {
+      ...markMigrationItemError(item, "invalid Codex plugin migration item"),
+      details: { ...item.details, code: "invalid_plugin_item" },
+    };
+  }
+  try {
+    const appCacheKey = await buildTargetCodexPluginAppCacheKey(ctx);
+    const appServer = resolveTargetCodexAppServer(ctx);
+    const result = await ensureCodexPluginActivation({
+      identity: policy,
+      installEvenIfActive: true,
+      request: async (method, requestParams) =>
+        await requestTargetCodexAppServerJson({
+          method,
+          requestParams,
+          timeoutMs: 60_000,
+          startOptions: appServer.start,
+          agentDir: resolveCodexMigrationTargets(ctx).agentDir,
+          config: ctx.config,
+          isolated: false,
+        }),
+      appCache: defaultCodexAppInventoryCache,
+      appCacheKey,
+    });
+    const baseDetails = {
+      ...item.details,
+      code: result.reason,
+      activationReason: result.reason,
+      ...codexPluginActivationReportState(result),
+      installAttempted: result.installAttempted,
+      diagnostics: result.diagnostics.map((diagnostic) => diagnostic.message),
+    };
+    if (result.ok) {
+      return {
+        ...item,
+        status: "migrated",
+        ...(result.reason === "already_active" ? { reason: "already active" } : {}),
+        details: baseDetails,
+      };
+    }
+    if (result.reason === CODEX_PLUGIN_AUTH_REQUIRED_REASON) {
+      return {
+        ...item,
+        status: "skipped",
+        reason: CODEX_PLUGIN_AUTH_REQUIRED_REASON,
+        details: {
+          ...baseDetails,
+          appsNeedingAuth: sanitizeAppsNeedingAuth(result.installResponse?.appsNeedingAuth ?? []),
+        },
+      };
+    }
+    if (result.reason === "plugin_missing" || result.reason === "marketplace_missing") {
+      return {
+        ...item,
+        status: "warning",
+        reason: result.reason,
+        message: `Codex plugin "${policy.pluginName}" could not be migrated automatically`,
+        details: {
+          ...baseDetails,
+          warningReason: CODEX_PLUGIN_LOAD_WARNING,
+        },
+      };
+    }
+    return {
+      ...item,
+      status: "error",
+      reason: result.reason,
+      details: baseDetails,
+    };
+  } catch (error) {
+    if (isCodexPluginInventoryLoadError(error)) {
+      return {
+        ...item,
+        status: "warning",
+        reason: "plugin_inventory_unavailable",
+        message: `Codex plugin "${policy.pluginName}" could not be migrated automatically`,
+        details: {
+          ...item.details,
+          code: "plugin_inventory_unavailable",
+          warningReason: CODEX_PLUGIN_LOAD_WARNING,
+          diagnostic: formatCodexMigrationError(error),
+        },
+      };
+    }
+    return {
+      ...item,
+      status: "error",
+      reason: formatCodexMigrationError(error),
+      details: {
+        ...item.details,
+        code: "plugin_install_failed",
+      },
+    };
+  }
+}
+
+function isCodexPluginInventoryLoadError(error: unknown): boolean {
+  const message = formatCodexMigrationError(error);
+  return message.includes("codex app-server plugin/list timed out");
+}
+
+function formatCodexMigrationError(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function resolveTargetCodexAppServer(ctx: MigrationProviderContext) {
+  return resolveCodexAppServerRuntimeOptions({
+    pluginConfig: readCodexPluginConfig(ctx.config),
+  });
+}
+
+async function requestTargetCodexAppServerJson(params: {
+  method: string;
+  requestParams?: unknown;
+  timeoutMs: number;
+  startOptions: ReturnType<typeof resolveTargetCodexAppServer>["start"];
+  agentDir: string;
+  config: MigrationProviderContext["config"];
+  isolated?: boolean;
+}): Promise<unknown> {
+  if (params.method !== "plugin/list") {
+    return await requestCodexAppServerJson(params);
+  }
+
+  const deadline = Date.now() + params.timeoutMs;
+  const discoveryTimeoutMs = targetCodexMarketplaceDiscoveryTimeoutMs();
+  const discoveryDeadline = Math.min(deadline, Date.now() + discoveryTimeoutMs);
+  let lastResponse: unknown;
+  let attempt = 0;
+  do {
+    attempt += 1;
+    const remainingMs = Math.max(1, discoveryDeadline - Date.now());
+    lastResponse = await requestCodexAppServerJson({
+      ...params,
+      timeoutMs: remainingMs,
+    });
+    if (hasOpenAiCuratedMarketplace(lastResponse)) {
+      return lastResponse;
+    }
+    if (Date.now() >= discoveryDeadline) {
+      return lastResponse;
+    }
+    const waitMs = Math.min(
+      TARGET_CODEX_MARKETPLACE_DISCOVERY_POLL_MS,
+      discoveryDeadline - Date.now(),
+    );
+    await sleep(waitMs);
+  } while (Date.now() < discoveryDeadline);
+
+  return lastResponse;
+}
+
+function hasOpenAiCuratedMarketplace(response: unknown): boolean {
+  if (!response || typeof response !== "object" || !("marketplaces" in response)) {
+    return false;
+  }
+  const marketplaces = (response as { marketplaces?: unknown }).marketplaces;
+  return (
+    Array.isArray(marketplaces) &&
+    marketplaces.some(
+      (marketplace) =>
+        marketplace &&
+        typeof marketplace === "object" &&
+        (marketplace as { name?: unknown }).name === CODEX_PLUGINS_MARKETPLACE_NAME,
+    )
+  );
+}
+
+function targetCodexMarketplaceDiscoveryTimeoutMs(): number {
+  const configured = Number(process.env[TARGET_CODEX_MARKETPLACE_DISCOVERY_TIMEOUT_ENV]);
+  if (Number.isFinite(configured) && configured >= 0) {
+    return configured;
+  }
+  return TARGET_CODEX_MARKETPLACE_DISCOVERY_TIMEOUT_MS;
+}
+
+function isCodexPluginLoadWarningItem(item: MigrationItem): boolean {
+  return (
+    item.kind === "plugin" &&
+    item.action === "install" &&
+    item.status === "warning" &&
+    item.details?.warningReason === CODEX_PLUGIN_LOAD_WARNING
+  );
+}
+
+async function sleep(ms: number): Promise<void> {
+  await new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+async function buildTargetCodexPluginAppCacheKey(ctx: MigrationProviderContext): Promise<string> {
+  const targets = resolveCodexMigrationTargets(ctx);
+  const appServer = resolveTargetCodexAppServer(ctx);
+  const authProfileId = resolveCodexAppServerAuthProfileIdForAgent({
+    agentDir: targets.agentDir,
+    config: ctx.config,
+  });
+  const accountId = await resolveCodexAppServerAuthAccountCacheKey({
+    authProfileId,
+    agentDir: targets.agentDir,
+    config: ctx.config,
+  });
+  const envApiKeyFingerprint = authProfileId
+    ? undefined
+    : resolveCodexAppServerEnvApiKeyCacheKey({
+        startOptions: appServer.start,
+      });
+  return buildCodexPluginAppCacheKey({
+    appServer,
+    agentDir: targets.agentDir,
+    authProfileId,
+    accountId,
+    envApiKeyFingerprint,
+  });
+}
+
+async function applyCodexPluginConfigItem(
+  ctx: MigrationProviderContext,
+  item: MigrationItem,
+  appliedItems: readonly MigrationItem[],
+): Promise<MigrationItem> {
+  const entries = appliedItems
+    .map(readAppliedPluginConfigEntry)
+    .filter((entry): entry is CodexPluginMigrationConfigEntry => entry !== undefined);
+  if (entries.length === 0) {
+    return markMigrationItemSkipped(item, "no selected Codex plugins");
+  }
+  const returnPatch = shouldReturnCodexPluginConfigPatch(ctx);
+  const configApi = ctx.runtime?.config;
+  const currentConfig = returnPatch
+    ? ctx.config
+    : (configApi?.current?.() as MigrationProviderContext["config"] | undefined);
+  if (!currentConfig) {
+    return markMigrationItemError(item, "config runtime unavailable");
+  }
+  const value = buildCodexPluginsConfigValue(entries, { config: currentConfig });
+  if (!ctx.overwrite && hasCodexPluginConfigConflict(currentConfig, value)) {
+    return markMigrationItemConflict(item, MIGRATION_REASON_TARGET_EXISTS);
+  }
+  const migratedItem: MigrationItem = {
+    ...item,
+    status: "migrated",
+    details: {
+      ...item.details,
+      path: [...CODEX_PLUGIN_CONFIG_PATH],
+      value,
+    },
+  };
+  if (returnPatch) {
+    return migratedItem;
+  }
+  if (!configApi?.mutateConfigFile) {
+    return markMigrationItemError(item, "config runtime unavailable");
+  }
+  try {
+    await configApi.mutateConfigFile({
+      base: "runtime",
+      afterWrite: { mode: "auto" },
+      mutate(draft) {
+        if (!ctx.overwrite && hasCodexPluginConfigConflict(draft, value)) {
+          throw new CodexPluginConfigConflictError(MIGRATION_REASON_TARGET_EXISTS);
+        }
+        writeMigrationConfigPath(draft as Record<string, unknown>, CODEX_PLUGIN_CONFIG_PATH, value);
+      },
+    });
+    return migratedItem;
+  } catch (error) {
+    if (error instanceof CodexPluginConfigConflictError) {
+      return markMigrationItemConflict(item, error.reason);
+    }
+    return markMigrationItemError(item, error instanceof Error ? error.message : String(error));
+  }
+}
+
+function readAppliedPluginConfigEntry(
+  item: MigrationItem,
+): CodexPluginMigrationConfigEntry | undefined {
+  if (item.status === "migrated") {
+    return readCodexPluginMigrationConfigEntry(item, true);
+  }
+  if (
+    item.status === "skipped" &&
+    item.reason !== CODEX_PLUGIN_NOT_SELECTED_REASON &&
+    item.reason === CODEX_PLUGIN_AUTH_REQUIRED_REASON
+  ) {
+    return readCodexPluginMigrationConfigEntry(item, false);
+  }
+  return undefined;
+}
+
+function readCodexPluginPolicy(item: MigrationItem): ResolvedCodexPluginPolicy | undefined {
+  const configKey = item.details?.configKey;
+  const marketplaceName = item.details?.marketplaceName;
+  const pluginName = item.details?.pluginName;
+  if (
+    typeof configKey !== "string" ||
+    marketplaceName !== CODEX_PLUGINS_MARKETPLACE_NAME ||
+    typeof pluginName !== "string"
+  ) {
+    return undefined;
+  }
+  return {
+    configKey,
+    marketplaceName: CODEX_PLUGINS_MARKETPLACE_NAME,
+    pluginName,
+    enabled: true,
+    allowDestructiveActions: true,
+  };
+}
+
+function codexPluginActivationReportState(result: CodexPluginActivationResult): {
+  installed?: boolean;
+  enabled?: boolean;
+} {
+  switch (result.reason) {
+    case "already_active":
+    case "installed":
+      return { installed: true, enabled: true };
+    case "auth_required":
+      return { installed: true, enabled: false };
+    case "disabled":
+    case "marketplace_missing":
+    case "plugin_missing":
+      return { installed: false, enabled: false };
+    case "refresh_failed":
+      return { installed: true, enabled: false };
+  }
+  const exhaustiveReason: never = result.reason;
+  return exhaustiveReason;
+}
+
+function sanitizeAppsNeedingAuth(apps: readonly v2.AppSummary[]): Array<{
+  id: string;
+  name: string;
+  needsAuth: boolean;
+}> {
+  return apps.map((app) => ({
+    id: app.id,
+    name: app.name,
+    needsAuth: app.needsAuth,
+  }));
+}

package/extensions/codex/src/migration/helpers.ts

@@ -0,0 +1,55 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { readJsonFileWithFallback } from "openclaw/plugin-sdk/json-store";
+import { pathExists } from "openclaw/plugin-sdk/security-runtime";
+
+export async function exists(filePath: string): Promise<boolean> {
+  return await pathExists(filePath);
+}
+
+export async function isDirectory(filePath: string | undefined): Promise<boolean> {
+  if (!filePath) {
+    return false;
+  }
+  try {
+    return (await fs.stat(filePath)).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+export function resolveUserHomeDir(): string {
+  return process.env.HOME?.trim() || os.homedir();
+}
+
+export function resolveHomePath(value: string): string {
+  if (value === "~") {
+    return resolveUserHomeDir();
+  }
+  if (value.startsWith("~/")) {
+    return path.join(resolveUserHomeDir(), value.slice(2));
+  }
+  return path.resolve(value);
+}
+
+export function sanitizeName(value: string): string {
+  return value
+    .trim()
+    .toLowerCase()
+    .replaceAll(/[^a-z0-9._-]+/gu, "-")
+    .replaceAll(/^-+|-+$/gu, "")
+    .slice(0, 64);
+}
+
+export async function readJsonObject(
+  filePath: string | undefined,
+): Promise<Record<string, unknown>> {
+  if (!filePath) {
+    return {};
+  }
+  const { value: parsed } = await readJsonFileWithFallback<unknown>(filePath, {});
+  return parsed && typeof parsed === "object" && !Array.isArray(parsed)
+    ? (parsed as Record<string, unknown>)
+    : {};
+}