Skip to content

Commit 1d77b63

Browse files
kentcdoddskentcdodds
committed
Update agent instructions and setup script in AGENTS.md and package.json
- Revised agent instructions to include a description of GratiText's purpose. - Added a new setup script section detailing the steps for building and preparing the app. - Updated the setup command in package.json to include dependencies for Playwright installation.
1 parent b05f236 commit 1d77b63

15 files changed

Lines changed: 157 additions & 18 deletions

‎AGENTS.md‎

Lines changed: 30 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -1,24 +1,37 @@
11
# Agent instructions
22

3-
## Data access
3+
GratiText helps people send thoughtful gratitude notes to loved ones on a
4+
regular schedule.
45

5-
- Use typed SQL (generated `sql` helpers with `prisma.$queryRawTyped`).
6-
- Do not use `prisma.$queryRaw` or `Prisma.sql`.
7-
- Exception: Prisma typed SQL filenames must be valid JS identifiers (no
8-
dashes), so the lower-kebab-case rule does not apply under `prisma/sql/`.
6+
## Essentials
97

10-
## Full gate before push
8+
- Node version: `^24`
9+
- Build: `npm run build` (runs `build:icons`, then `react-router build`)
10+
- Typecheck: `npm run typecheck` (runs `react-router typegen`, then `tsc`)
1111

12-
You can push when you feel confident things are working, but immediately after
13-
pushing, run the full gate to ensure everything is working (with the exception
14-
of formatting, these can be run simultaneously with `npm run validate`).
12+
### Setup script
1513

16-
- Run formatting (`npm run format`).
17-
- Run type checking (`npm run typecheck`).
18-
- Run linting (`npm run lint -- --fix`).
19-
- Run tests (`npm run test`, plus any relevant e2e suites).
20-
- Only push after all checks pass.
14+
Run `npm run setup` to:
2115

22-
If anything changes as a result of running the full gate, commit and push that.
23-
If you need to make changes to the codebase, do so in a separate commit and push
24-
that as well.
16+
- Build the app
17+
- Ensure the Prisma DB is present
18+
- Generate the Prisma SQL
19+
- Migrate the DB
20+
- Seed the DB
21+
- Install the Playwright browsers
22+
23+
## More instructions
24+
25+
- [Data access rules](docs/agents/data-access.md)
26+
- [Git workflow rules](docs/agents/git-workflow.md)
27+
- [Routing](docs/agents/routing.md)
28+
- [Auth and session](docs/agents/auth-session.md)
29+
- [Environment and config](docs/agents/env-config.md)
30+
- [Testing](docs/agents/testing.md)
31+
- [Cron jobs and scheduling](docs/agents/cron-jobs.md)
32+
- [Caching and performance](docs/agents/caching-performance.md)
33+
- [UI and styling](docs/agents/ui-and-styling.md)
34+
- [Error handling](docs/agents/error-handling.md)
35+
- [Naming and structure](docs/agents/naming-and-structure.md)
36+
- [Scripts](docs/agents/scripts.md)
37+
- [Security](docs/agents/security.md)

‎docs/agents/auth-session.md‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
# Auth and session
2+
3+
- Session cookie uses `en_session`, `sameSite: 'lax'`, `httpOnly: true`, and
4+
`secure` in production; secrets come from `SESSION_SECRET` (comma-separated).
5+
- Session expiration rules:
6+
- Idle timeout: 14 days.
7+
- Absolute max lifetime: 90 days from original creation.
8+
- Sessions renew when within 7 days of expiration, but never beyond the
9+
absolute max.
10+
- Use `getUserId`, `requireUserId`, and `requireAnonymous` helpers for auth
11+
flow.
12+
- `requireUserWithPermission`/`requireUserWithRole` enforce access and respond
13+
with 403 JSON on failure.

‎docs/agents/caching-performance.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
# Caching and performance
2+
3+
- Caching uses `@epic-web/cachified` with two layers:
4+
- SQLite cache stored at `CACHE_DATABASE_PATH`.
5+
- In-memory LRU cache (`lru-cache`) for hot entries.
6+
- Cache writes happen on the primary instance; non-primary instances forward
7+
updates via `updatePrimaryCacheValue`.
8+
- `cachified()` wraps `@epic-web/cachified` and adds Server-Timing metrics via
9+
`cachifiedTimingReporter`.
10+
- Use `makeTimings()` and `time()` from `app/utils/timing.server.ts` to emit
11+
Server-Timing headers and measure important work.

‎docs/agents/cron-jobs.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
# Cron jobs and scheduling
2+
3+
- Cron processing is implemented in `app/utils/cron.server.ts`.
4+
- `init()` starts a `setIntervalAsync` loop every 5 seconds to send due texts.
5+
- `sendNextTexts()`:
6+
- Queries recipients via typed SQL (`getrecipientsforcron`).
7+
- Processes a 30-minute reminder window.
8+
- Uses sentinel dates for invalid cron strings to prevent reprocessing.

‎docs/agents/data-access.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
# Data access
2+
3+
- Use typed SQL generated in `prisma/sql/` with `prisma.$queryRawTyped`.
4+
- Do not use `prisma.$queryRaw` or `Prisma.sql`.
5+
- Filename exception: Prisma typed SQL files must be valid JS identifiers (no
6+
dashes), so the lower-kebab-case rule does not apply under `prisma/sql/`.

‎docs/agents/env-config.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
# Environment and config
2+
3+
- Environment variables are validated with Zod in `app/utils/env.server.ts`.
4+
- Call `init()` early at server startup to validate required env vars.
5+
- Only expose client-safe vars via `getEnv()`; do not add secrets there.
6+
- Required env vars include:
7+
- `DATABASE_PATH`, `DATABASE_URL`, `CACHE_DATABASE_PATH`
8+
- `SESSION_SECRET`, `INTERNAL_COMMAND_TOKEN`, `HONEYPOT_SECRET`
9+
- `TWILIO_TOKEN`, `TWILIO_SID`
10+
- `STRIPE_SECRET_KEY`, `STRIPE_BASIC_PAYMENT_LINK`, `STRIPE_BASIC_PRODUCT`,
11+
`STRIPE_PREMIUM_PAYMENT_LINK`, `STRIPE_PREMIUM_PRODUCT`
12+
- `ALLOW_INDEXING` is optional.
13+
14+
When initializing the environment, you should copy the `.env.example` file
15+
to `.env` and these values will be filled in with mocked values.

‎docs/agents/error-handling.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
# Error handling
2+
3+
- Prefer `GeneralErrorBoundary` from `app/components/error-boundary.tsx` for
4+
route error handling with per-status handlers.
5+
- Unexpected errors are reported to Sentry; route errors are handled separately.
6+
- Use `getErrorMessage()` from `app/utils/misc.tsx` to normalize unknown errors.

‎docs/agents/git-workflow.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
# Git workflow
2+
3+
Push when you feel confident things are working, then immediately run the full
4+
gate.
5+
6+
- Run formatting: `npm run format`.
7+
- Run linting with fixes: `npm run lint -- --fix`.
8+
- Run type checking: `npm run typecheck`.
9+
- Run tests: `npm run test`, plus any relevant e2e suites
10+
(`npm run test:e2e:run`).
11+
- `npm run validate` can replace `typecheck`, `test`, and `test:e2e:run`, but it
12+
does not run `format` or `lint -- --fix`.
13+
14+
If anything changes as a result of running the full gate, commit and push that.
15+
If you need to make changes to the codebase, do so in a separate commit and push
16+
that as well.

‎docs/agents/naming-and-structure.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
# Naming and project structure
2+
3+
- Use `*.server.*` and `*.client.*` for server/client-specific modules.
4+
- Tests use `*.test.{js,jsx,ts,tsx}` naming.
5+
- Files starting with `__` are treated as non-route helpers.
6+
- Path aliases:
7+
- `#app/*` maps to `app/*`
8+
- `#tests/*` maps to `tests/*`

‎docs/agents/routing.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
# Routing
2+
3+
- Route config lives in `app/routes.ts` and uses `remix-flat-routes` with
4+
`remixRoutesOptionAdapter`.
5+
- Files ignored as routes: dotfiles, `*.css`, `*.test.*`, `__*`, `*.server.*`,
6+
and `*.client.*`.
7+
- If a route filename needs the literal word `server` or `client`, use escape
8+
brackets like `my-route.[server].tsx` so it is not ignored.

0 commit comments

Comments
 (0)