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:

npm install
just build
just test

Local Worker:

just build
just migrate-local
just dev

Remote dev:

just migrate-dev
just deploy-dev

Remote prod:

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:

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

Prod D1:

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:

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:

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:

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:

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:

just dev-admin wahyd4@gmail.com

Or open:

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:

just build
just test

For import script changes:

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.