Skip to main content

Dev setup

How a developer (or AI assistant) gets Helm code changes shipping. As of 2026-05-13 the workflow is deploy directly to the real Worker — there is no wrangler dev loop. Layer 1 Google OAuth gates the production URL, so iterating against the real deployment is safe even with half-built features behind a Sys Admin sign-in.

v0.2 — local-dev mode removed

The previous wrangler dev --local workflow is gone. The dev script + predev hook have been removed from package.json. Bootstrap commands below assume you're cloning a fresh checkout and deploying against the existing remote D1 (kvick-helm-swicked, id 134ea8a4-8582-4fdc-84ec-f0eb8f4e4b60).

Prerequisites​

  • Node.js 20+ (node --version)
  • npm 10+
  • Python 3.11+ (for AIM ETL only; not needed for app dev)
  • A Cloudflare account (free tier is fine)
  • wrangler CLI: npm i -g wrangler
  • Git

One-time setup​

# Clone
git clone git@github.com:KVICKADMIN/KVICK.BIKE_SWICKED.git
cd KVICK.BIKE_SWICKED

# Install dependencies
npm install

# Wrangler login — Cloudflare account: hello@kvick.ca
wrangler login

Confirm wrangler.jsonc already has the remote D1 wired (you should see "database_id": "134ea8a4-8582-4fdc-84ec-f0eb8f4e4b60").

Get on the OAuth allowlist​

Your Google email needs to be in the Swicked allowlist before you can sign in:

wrangler d1 execute DB --remote --command "SELECT authorized_google_emails FROM shop_config"

If your email isn't there, ask the Sys Admin to add it via POST /api/auth/allowlist in the deployed UI, or update directly with:

wrangler d1 execute DB --remote --command "UPDATE shop_config SET authorized_google_emails = json_insert(authorized_google_emails, '$[#]', 'your.email@example.com')"

Apply migrations to remote D1​

When migrations/ has new files, push them:

wrangler d1 migrations apply DB --remote

(There is no local-D1 path anymore. Migrations land on remote directly.)

Set Pages secrets (one-time per shop)​

wrangler secret put GOOGLE_CLIENT_SECRET   # paste the OAuth client secret
wrangler secret put ANTHROPIC_API_KEY      # if AI Support is wired
wrangler secret put STRIPE_SECRET_KEY      # when Stripe Terminal lands

The GOOGLE_CLIENT_ID lives in wrangler.jsonc under vars (public).

Deploy​

npm run deploy
# = node scripts/build_info.js && wrangler deploy

Open the deployed URL (currently mockup-only-swicked-helm.solitary-poetry-5fcc.workers.dev). You'll be redirected to Google → after sign-in you land on the PIN overlay → enter your PIN, or 466687 for Sys Admin.

(Optional, rare) Local SQLite for sandbox work​

If you genuinely need an out-of-band local SQLite (e.g. to rebuild the database from AIM dumps without touching prod):

python migrate_aim.py --all --target=local

This populates a local SQLite file under %LOCALAPPDATA%/kvick-helm-wrangler/.... The deployed Worker does NOT see this — it's a side-channel for data work only. The day-to-day code loop is "edit + npm run deploy."

What to do next​

Troubleshooting​

OAuth redirect lands on the SPA shell instead of bouncing to Google — wrangler.jsonc is missing assets.run_worker_first: true. Without it, the static-asset binding intercepts top-level browser navigations to /api/auth/google/start before the Worker runs. Fixed in commit dd9eafe; check that flag if you see the symptom.

"Email not authorized for this shop" — your Google account isn't on shop_config.authorized_google_emails. Get the Sys Admin to add it, or update directly with wrangler d1 execute DB --remote ....

Migration fails partway — D1 migrations are not transactional across files. Roll back manually with wrangler d1 execute DB --remote --command "DROP TABLE ..." for the partially-applied tables, then re-run wrangler d1 migrations apply DB --remote.

Can't sign in with admin code — make sure your device has a valid helm_device cookie first (the OAuth gate is in front of the PIN screen). If you're stuck on the OAuth callback, check the deployed Worker logs for "email_not_allowed" or "state_mismatch."

See also​