heygo/agent.md

# Heygo Agent Guide

This repo is the Cloudflare Workers + React implementation of Heygo, a shortlinks app. Treat this repository as the source of truth for Heygo. The older Linux/Django Links app is reference material only and must not be modified from here.

## Project Shape

- Frontend: React + Vite in `src/`.
- Worker/API: Cloudflare Worker in `worker/`.
- D1 schema: `migrations/`.
- Import/export utilities: `scripts/`.
- Deployment configs:
  - Local/default: `wrangler.jsonc`
  - Dev: `wrangler.dev.jsonc`
  - Prod: `wrangler.prod.jsonc`
- Dev public host: `dev.heygo.cc`.
- Dev private host: `my.dev.heygo.cc`.
- Prod public host: `heygo.cc`.
- Prod private host: `my.heygo.cc`.

The Worker serves the built SPA assets and handles `/api/*`, public redirects, private redirects, and `/links/:id/go` app redirects.

## Core Commands

Install and verify:

```bash
npm install
just build
just test
```

Local Worker:

```bash
just build
just migrate-local
just dev
```

Remote dev:

```bash
just migrate-dev
just deploy-dev
```

Remote prod:

```bash
just migrate-prod
just deploy-prod
```

Use `just` with no arguments to list available recipes.

## D1 And Wrangler

Use the environment-specific Wrangler config explicitly for remote D1 work.

Dev D1:

```bash
npx wrangler d1 execute heygo-shortlinks-dev --config wrangler.dev.jsonc --remote --command "SELECT 1"
```

Prod D1:

```bash
npx wrangler d1 execute heygo-shortlinks --config wrangler.prod.jsonc --remote --command "SELECT 1"
```

Do not assume `wrangler.jsonc` points at dev. It is the local/default config and uses placeholder remote IDs.

## Importing Links

Private links should be owned by the admin user with email `wahyd4@gmail.com`. Do not hardcode a user id in new import tooling; resolve the user by email from the target D1 database. User IDs can differ between local, dev, and prod.

For JSONL imports produced by `scripts/export-django-links.py`, use:

```bash
npm run import:links -- \
  --file ./exports/shortlinks.jsonl \
  --config wrangler.dev.jsonc
```

The importer defaults to `wahyd4@gmail.com`. Override only when intentionally importing for a different admin:

```bash
npm run import:links -- \
  --file ./exports/shortlinks.jsonl \
  --owner-email other-admin@example.com \
  --config wrangler.dev.jsonc
```

For the checked-in SQL import file, confirm the `owner_user_id` matches the target D1 user before running it:

```bash
npx wrangler d1 execute heygo-shortlinks-dev \
  --config wrangler.dev.jsonc \
  --remote \
  --command "SELECT id, email, role FROM users WHERE email='wahyd4@gmail.com'"
```

Then import:

```bash
npx wrangler d1 execute heygo-shortlinks-dev \
  --config wrangler.dev.jsonc \
  --remote \
  --file imports/links-import.sql
```

The SQL file is destructive for that owner's private links because it starts by deleting existing private links for the owner. Prefer the JSONL importer for future repeatable imports because it resolves the owner by email and skips existing active private aliases.

## Authentication

Local development does not use OAuth. Start the Worker and use:

```bash
just dev-admin wahyd4@gmail.com
```

Or open:

```text
http://localhost:8787/#/dev-login
```

Remote dev/prod use OAuth. Admin status is controlled by `ADMIN_EMAILS` in the matching Wrangler config and persisted user role.

## Coding Notes

- Keep frontend edits consistent with existing React component patterns in `src/components` and route-level views in `src/routes`.
- API routes live under `worker/routes`; shared Worker helpers live under `worker/lib`.
- Alias validation belongs in `worker/lib/aliases.ts`.
- URL template parsing and resolution belongs in `worker/lib/templates.ts`.
- Custom markdown link rendering belongs in `worker/lib/custom-link.ts`.
- Keep DB schema changes in numbered SQL migrations under `migrations/`.
- After schema changes, update tests that assert schema behavior.
- Do not put Node-only script code into `src`, `worker`, or files included by `tsconfig.json`.

## Verification Expectations

For normal code changes:

```bash
just build
just test
```

For import script changes:

```bash
npm run import:links -- --help
npm run import:links -- --file <jsonl> --config wrangler.dev.jsonc --dry-run
```

For remote D1 changes, verify with a direct count or sample query after the command completes.

## Worktree Safety

The worktree may contain user edits. Check `git status --short` before editing, avoid unrelated files, and do not revert changes you did not make.