MagicAIBuilder: Instructions file for Codex

MagicAIBuilder — Coding Standards

These rules apply to ALL code written in this project. Read docs/references/typescript-patterns.md before any refactoring session or when writing complex logic.

Language & Runtime

• TypeScript strict mode ("strict": true). Zero any — use unknown + type guards instead.
• Target: ES2017+. Use modern syntax: optional chaining, nullish coalescing, satisfies, using for cleanup.
• Node 20+, Next.js 15 (App Router), React 19.

Type Safety — Non-Negotiable Rules

No type assertions (as)

Type assertions bypass the compiler. Use type guards or discriminated unions instead:

// ❌ NEVER
const cat = value as CardCategory;

// ✅ ALWAYS
function isCardCategory(v: string): v is CardCategory {
  return CARD_CATEGORIES.includes(v as CardCategory);
}
if (isCardCategory(value)) {
  /* value is now CardCategory */
}

No non-null assertions (!)

They crash at runtime. Use optional chaining + nullish coalescing or early returns:

// ❌ NEVER
const name = card!.name;

// ✅ ALWAYS
const name = card?.name ?? "Unknown";

No eslint-disable without a ticket/issue reference

Every disable MUST have a comment explaining WHY and linking to the issue that will fix it:

// eslint-disable-next-line react-hooks/exhaustive-deps -- #42: searchSignal is a ref, not state

Exhaustive switch with never guard

Every switch on a union type MUST have an exhaustive check:

function getPairingLabel(type: CommanderPairingType): string {
  switch (type) {
    case "none":
      return "Aucun";
    case "partner":
      return "Partner";
    // ... all cases
  }
  const _exhaustive: never = type;
  return _exhaustive;
}

Discriminated unions over boolean flags

Prefer { role: "commander" } over { isCommander: true, isPartner: false }:

// ❌ Allows invalid states (isCommander && isPartner both true)
interface DeckCard {
  isCommander: boolean;
  isPartner: boolean;
}

// ✅ Only valid states are representable
type CardRole = "commander" | "partner" | "companion" | "main";
interface DeckCard {
  role: CardRole; /* ... */
}