Codex CLI: configurazione TypeScript, schema Prisma e middleware Express

Proseguiamo con il nostro esperimento dedicato all'automatizzazione del setup di un progetto Node.js con Codex CLI, naturalmente senza toccare la tastiera. Il prossimo passaggio riguarda la configurazione TypeScript in maniere quasi perfetta (o quasi).

Configurazione TypeScript con Codex CLI

Nel nostro progetto il file tsconfig.json che è stato generato automaticamente era articolato e rifletteva una buona comprensione delle esigenze di un progetto ESM (ES Modules) adatto per il web contemporaneo:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "lib": ["ES2022"],
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "declaration": true,
    "declarationMap": true,
    "sourceMap": true,
    "resolveJsonModule": true,
    "allowImportingTsExtensions": false,
    "paths": {
      "@/*": ["./src/*"]
    }
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist", "tests"]
}

Un commento ragionato, e "umano", al codice

La scelta di "moduleResolution": "bundler" è interessante e rispecchia le raccomandazioni più recenti per progetti che usano ESM con TypeScript 5.x. L'abilitazione di path con alias @/* per evitare import relativi profondi è una comodità che in molti progetti di sviluppo viene aggiunta solo mesi dopo l'inizio dei lavori. Il file di tsconfig.build.json separato, che in pratica escludeva i test dalla build di produzione, in questo caso era presente e corretto.

Il problema, semmai, poteva essere rilevato in "allowImportingTsExtensions": false. Con ESM puro in Node.js, gli import devono includere l'estensione del file, e TypeScript con moduleResolution: bundler in un contesto Node.js, quindi non in un bundler reale, crea una tensione non risolta tra la convenzione TypeScript di importare senza estensione e il requisito ESM di importare con estensione .js che TypeScript risolve al file .ts corrispondente.

Il progetto, così com'era configurato fino a quel momento, avrebbe richiesto una modifica manuale alla configurazione prima di compilare correttamente. Non si sarebbe trattato di un errore catastrofico, ma sicuramente avremmo dovuto fare i conti con un ostacolo per chiunque avesse clonato il repository e provato ad effettuare la prima build.

Lo schema Prisma e i middleware Express

Dopo la configurazione di Typescript, Codex CLI ha generato uno schema Prisma iniziale con i modelli per utenti e refresh token, la struttura di base dei middleware Express, e il file di entry point. Lo schema Prisma risultava sufficientemente pulito e rifletteva egregiamente le best practice correnti:

// prisma/schema.prisma
generator client {
  provider = "prisma-client-js"
}
datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
}
model User {
  id           String   @id @default(cuid())
  email        String   @unique
  passwordHash String   @map("password_hash")
  createdAt    DateTime @default(now()) @map("created_at")
  updatedAt    DateTime @updatedAt @map("updated_at")
  refreshTokens RefreshToken[]
  @@map("users")
}
model RefreshToken {
  id        String   @id @default(cuid())
  token     String   @unique
  userId    String   @map("user_id")
  expiresAt DateTime @map("expires_at")
  createdAt DateTime @default(now()) @map("created_at")
  user      User     @relation(fields: [userId], references: [id], onDelete: Cascade)
  @@index([userId])
  @@index([expiresAt])
  @@map("refresh_tokens")
}

Codex CLI e generazione degli ID

In questo caso, la scelta di cuid() invece di uuid() come strategia di generazione degli ID è una decisione che Codex CLI ha preso senza commentarla. Intendiamoci, non è sbagliata, i CUID sono più corti, ordinabili, e meno soggetti a collisioni in contesti distribuiti. È però il tipo di scelta che in un team ha implicazioni su come vengono esposti gli ID nelle API, su come vengono indicizzati nel database, e su come vengono gestiti nei test.

Un agente in grado di documentare attentamente le proprie scelte renderebbe molto più facile la review dell'output. Codex CLI in questa sessione non lo ha fatto.

Il middleware di autenticazione JSON Web Token era funzionalmente corretto e gestiva sia l'access token che il refresh token con la logica di rotazione, ma usava any in tre punti critici del codice TypeScript. Una scorciatoia che disabilita il type checking esattamente dove sarebbe più utile.

Non è un bug, ma è il tipo di debito tecnico che si accumula in modo silenzioso e che, in un progetto in fase di produzione, genera prima o poi un errore di runtime non intercettato dal compilatore.