KevinArce/create-bun-api

# Add an endpoint

1. **Baseline:** run `bun run verify`. If it already fails, fix that first (verify-and-debug skill) or
   report it. Don't build on a red baseline.
2. **Decide where the code goes:**
   - New resource: a new folder `src/modules/<name>/`. `<name>` is plural and lowercase, e.g. `notes`.
   - New route on an existing resource: that module's `<name>.routes.ts`, with logic in `<name>.service.ts`.
   - New table or column: follow the add-model skill first.
3. **Write the module.** A complete, tested example is in
   [references/notes-module.md](references/notes-module.md); copy its shape.
   - `<name>.schema.ts`: `t` schemas for bodies, params, and responses, plus `typeof X.static` types.
   - `<name>.repository.ts`: prepared SQL. Scope rows by owner (`user_id`) for per-user data.
   - `<name>.service.ts`: business rules. Throw `notFound()`, `conflict()`, and the other helpers from `src/lib/errors.ts`.
   - `<name>.routes.ts`: `new Elysia({ prefix: "/<name>", tags: ["<name>"] })`. Add

# Add or change a model

1. **Append a migration** to `src/db/migrations.ts` with the next id (`000N_<verb>_<table>`). Never edit,
   reorder, or delete a migration that may already have run somewhere.
2. **SQL conventions:**
   - Ids are `INTEGER PRIMARY KEY AUTOINCREMENT`. Columns are `snake_case`.
   - Timestamps: `TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now'))`.
   - Foreign keys are enforced. Write `REFERENCES users(id) ON DELETE CASCADE` and index every
     foreign key column.
   - Use `COLLATE NOCASE` for case-insensitive unique text such as emails.
   - One migration may contain several statements.

   ```ts
   {

# Create a Bun API project

1. Optional, fast: `bunx create-bun-api doctor --json`. If `ok` is false, follow each failed check's
   `hint`. The tool never installs software itself. If Bun is missing, tell the user how to install it
   (https://bun.com/docs/installation); don't run remote install scripts.
2. Create the project:

   ```bash
   bunx create-bun-api <dir> --yes --json        # same as: bun create bun-api <dir> --yes --json
   ```

   This writes the files, installs from the committed lockfile, makes a first git commit (skipped
   inside an existing repo), and runs the project's own `bun run verify`.
   Use `--dry-run` to preview the file list, or `--no-install` when offline.

# Verify and debug

1. Run `bun run verify --json`. It prints `{ "ok": …, "steps": [{ "id", "ok", "ms", "command", "output"? }] }`.
   `output` holds the last 40 lines of a failing step. Every step runs even after a failure.
2. Fix failures in this order, because earlier ones often cause later ones:

| Step | Reproduce alone | Usual causes |
| --- | --- | --- |
| `typecheck` | `bun run typecheck` | Wrong import path. A status code missing from the route's `response` map (for 204, use `status(204, undefined)` and `204: t.Void()`). Possibly-`undefined` values from indexed access (`noUncheckedIndexedAccess`). |
| `lint` | `bun run lint` | Run `bun run format` first; it fixes formatting and import order. Whatever remains is real: unused code or `any`. |
| `test` | `bun test <file>` or `bun test -t "<name>"` | Read the expected-versus-received diff. A wrong HTTP status usually means an object was returned instead of an error helper thrown. |
[Credential-related source omitted]

3. Rerun `bun run verify --json` until `ok` is `true`. Then report which steps ran.