Function parsePluginConfig

packages/plugin/src/config/index.ts:216–376

(
    rawConfig: Record<string, unknown>,
    recoveredTopLevelKeys: string[] = [],
)

}

function parsePluginConfig(
    rawConfig: Record<string, unknown>,
    recoveredTopLevelKeys: string[] = [],
): MagicContextPluginConfig & { configWarnings?: string[] } {
    // Pre-Zod shim: reshape legacy experimental.* graduated keys so the user's
    // opt-in/out state survives upgrades even when they never run `doctor`.
    const preMigrationWarnings: string[] = [];
    const migratedExperimental = migrateLegacyExperimental(rawConfig, preMigrationWarnings);
    // Dreamer v2: convert the legacy v1 dreamer shape (window schedule, tasks
    // array, user_memories/pin_key_files blocks) into the per-task `tasks` record.
    // Runs AFTER migrate-experimental so experimental.user_memories (already
    // relocated to dreamer.user_memories above) is folded into the v2 tasks here.
    const migratedDreamer = migrateDreamerV2(migratedExperimental, preMigrationWarnings);
    const migrated = migrateLegacyAgentEnabledInMemory(migratedDreamer, preMigrationWarnings);
    const parsed = MagicContextConfigSchema.safeParse(migrated);
    const disabledHooks = Array.isArray(rawConfig.disabled_hooks)
        ? rawConfig.disabled_hooks.filter((value): value is string => typeof value === "string")
        : undefined;
    const command =
        typeof rawConfig.command === "object" && rawConfig.command !== null
            ? (rawConfig.command as MagicContextPluginConfig["command"])
            : undefined;

    if (parsed.success) {
        return {
            ...parsed.data,
            disabled_hooks: disabledHooks,
            command,
            ...(preMigrationWarnings.length > 0 ? { configWarnings: preMigrationWarnings } : {}),
        };
    }

    // Full parse failed — recover field-by-field using defaults for invalid fields.
    // Agent configs (historian, dreamer, sidekick) are dropped on error rather than defaulted
    // because wrong model config could run expensive models or fail silently.
    const defaults = MagicContextConfigSchema.parse({});
    const warnings: string[] = [];

    // Build a patched copy of rawConfig, replacing invalid fields with undefined
    // so Zod fills in defaults on the second parse.
    const errorPaths = new Set<string>();
    // Collect any custom Zod messages per top-level key so a field with an
    // explanatory `.max(..., "why")` / `.refine(..., "why")` message surfaces the
    // reason to the user instead of a bare "invalid value" (e.g. issue #111's
    // execute_threshold cache-safety explanation). Only non-default Zod messages
    // are kept — the generic "Too big"/"Invalid input" boilerplate adds nothing.
    const customMessagesByKey = new Map<string, string>();
    // Per top-level key, the set of FULL error paths (e.g. ["memory","auto_search"]).
    // Used to prune only the invalid nested leaf instead of the whole block.
    const issuePathsByKey = new Map<string, PropertyKey[][]>();
    const GENERIC_ZOD_PREFIXES = ["Too big", "Too small", "Invalid input", "Invalid", "Expected"];
    for (const issue of parsed.error.issues) {
        const topKey = issue.path[0];
        if (topKey !== undefined) {
            const key = String(topKey);
            errorPaths.add(key);
            const paths = issuePathsByKey.get(key) ?? [];
            paths.push([...issue.path]);