@kodelyth/codex 2026.5.42 → 2026.6.1

package/src/migration/apply.ts

@@ -1,501 +0,0 @@
-import path from "node:path";
-import {
-  applyMigrationManualItem,
-  markMigrationItemConflict,
-  markMigrationItemError,
-  markMigrationItemSkipped,
-  MIGRATION_REASON_TARGET_EXISTS,
-  summarizeMigrationItems,
-  writeMigrationConfigPath,
-} from "klaw/plugin-sdk/migration";
-import {
-  archiveMigrationItem,
-  copyMigrationFileItem,
-  withCachedMigrationConfigRuntime,
-  writeMigrationReport,
-} from "klaw/plugin-sdk/migration-runtime";
-import type {
-  MigrationApplyResult,
-  MigrationItem,
-  MigrationPlan,
-  MigrationProviderContext,
-} from "klaw/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 `klaw 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 =
-  "KLAW_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/src/migration/helpers.ts

@@ -1,55 +0,0 @@
-import fs from "node:fs/promises";
-import os from "node:os";
-import path from "node:path";
-import { readJsonFileWithFallback } from "klaw/plugin-sdk/json-store";
-import { pathExists } from "klaw/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>)
-    : {};
-}