2026-ify this whole thing

Author: Patrick

.env.example

@@ -0,0 +1,5 @@
+DATABASE_URL="file:./prisma/dev.db"
+PORT=3000
+POETRY_API_BASE_URL="https://poetrydb.org"
+REQUEST_TIMEOUT_MS=5000
+NODE_ENV=development

.github/workflows/codeql-analysis.yml

@@ -9,16 +9,13 @@
 # the `language` matrix defined below to confirm you have the correct set of
 # supported CodeQL languages.
 #
-name: "CodeQL"
+name: CodeQL
 
 on:
   push:
-    branches: [ master ]
+    branches: [master]
   pull_request:
-    # The branches below must be a subset of the branches above
-    branches: [ master ]
-#   schedule:
-#     - cron: '39 6 * * 5'
+    branches: [master]
 
 jobs:
   analyze:
@@ -32,24 +29,28 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        language: [ 'javascript' ]
-        # CodeQL supports [ 'cpp', 'csharp', 'go', 'java', 'javascript', 'python' ]
-        # Learn more:
-        # https://docs.github.com/en/free-pro-team@latest/github/finding-security-vulnerabilities-and-errors-in-your-code/configuring-code-scanning#changing-the-languages-that-are-analyzed
+        language: ['javascript-typescript']
 
     steps:
-    - name: Checkout repository
-      uses: actions/checkout@v4
+      - name: Checkout repository
+        uses: actions/checkout@v4
 
-    # Initializes the CodeQL tools for scanning.
-    - name: Initialize CodeQL
-      uses: github/codeql-action/init@v3
-      with:
-        languages: ${{ matrix.language }}
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@v3
+        with:
+          languages: ${{ matrix.language }}
 
-    # Autobuild attempts to build any compiled languages  (C/C++, C#, or Java).
-    - name: Autobuild
-      uses: github/codeql-action/autobuild@v3
+      - name: Use Node.js 22
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22.x
+          cache: npm
 
-    - name: Perform CodeQL Analysis
-      uses: github/codeql-action/analyze@v3
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build project
+        run: npm run build
+
+      - name: Perform CodeQL Analysis
+        uses: github/codeql-action/analyze@v3

.github/workflows/node.js.yml

@@ -1,9 +1,9 @@
-# This workflow will do a clean install of node dependencies, build the source code and run tests across different versions of node
-# For more information see: https://help.github.com/actions/language-and-framework-guides/using-nodejs-with-github-actions
+name: CI
 
-name: Run tests
-
-on: [push, pull_request]
+on:
+  push:
+    branches: [master]
+  pull_request:
 
 jobs:
   test:
@@ -12,15 +12,30 @@ jobs:
     strategy:
       matrix:
         node-version: [22.x]
-        # Node 20+ required by Apollo Server 5 and Prisma 7
 
     steps:
       - uses: actions/checkout@v4
+
       - name: Use Node.js ${{ matrix.node-version }}
         uses: actions/setup-node@v4
         with:
           node-version: ${{ matrix.node-version }}
-          cache: 'npm'
-      - run: npm ci
-      - run: npx prisma generate
-      - run: npm test
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Generate Prisma client
+        run: npm run db:generate
+
+      - name: Generate GraphQL types
+        run: npm run codegen
+
+      - name: Lint
+        run: npm run lint
+
+      - name: Typecheck
+        run: npm run typecheck
+
+      - name: Test
+        run: npm run test

.gitignore

@@ -1 +1,9 @@
 node_modules
+dist
+coverage
+.env
+.DS_Store
+plans
+prisma/*.db
+prisma/*.db-journal
+src/generated/prisma

.prettierrc

@@ -0,0 +1,48 @@
+# AGENTS.md
+
+## Purpose
+
+This repository is a teaching showcase for a modern GraphQL-to-SQL stack using Apollo Server, Express, Prisma, TypeScript, SQLite, and a second upstream data source.
+
+## Repo Map
+
+- `src/server.ts`: process bootstrap, environment loading, shutdown wiring
+- `src/app.ts`: Express and Apollo assembly
+- `src/config`: environment parsing and logging
+- `src/graphql`: SDL files, typed context, and resolvers
+- `src/services`: domain services and upstream API client
+- `src/data`: Prisma client factory and repositories
+- `prisma`: Prisma schema, migrations, and seed script
+
+## Required Commands
+
+- `npm run dev`: local development server
+- `npm run build`: Prisma generate, GraphQL codegen, and TypeScript build
+- `npm run typecheck`: strict TypeScript verification
+- `npm run lint`: Biome checks
+- `npm run format`: Biome formatter
+- `npm run test`: Prisma generate, GraphQL codegen, and Vitest suite
+- `npm run db:migrate`: apply the committed migration set
+- `npm run db:seed`: seed the SQLite database
+
+## Generated Files Policy
+
+- `src/generated/prisma/**` is generated by `npm run db:generate` and should not be edited by hand.
+- `src/graphql/__generated__/resolvers-types.ts` is generated by `npm run codegen` and should not be edited by hand.
+- If a schema, context, or Prisma model changes, regenerate the relevant output and include the generated diff in the same change.
+- For new Prisma schema changes, create a development migration with `npx prisma migrate dev --name <change>` on Node 22, then commit the resulting migration files.
+
+## Workflow Guardrails
+
+- Keep GraphQL SDL in `.graphql` files and keep resolver functions thin.
+- Put persistence details in repositories and business behavior in services.
+- Prefer adding or updating tests alongside code changes.
+- Do not couple tests to Apollo internals when the HTTP boundary can be exercised instead.
+- Keep README examples aligned with the current schema and scripts.
+
+## Review Checklist
+
+- Build, typecheck, lint, and tests all pass.
+- Prisma and GraphQL generated files are up to date.
+- Environment variable changes are reflected in `.env.example` and README.
+- Public GraphQL examples in README match the current schema.