Harris Boat Works - Mercury Repower

Mercury Repower

Mercury Repower is Harris Boat Works' public Mercury outboard catalogue and quote builder.

Source and release authority

• GitHub harrisboatworks/mercury-builder-pro on main is the authoritative source.
• HBW's Vercel project is the production release path. Merges and production deployments require explicit authorization.
• Lovable may be used as an optional editor, but do not rely on automatic GitHub synchronization without verifying it first.

Local setup

Use Node 22.22.2 or newer on the 22 line, as declared in engines.node.

npm ci --ignore-scripts
npm run dev

The Vite development server runs on http://localhost:8080.

Quick validation

For a normal small frontend change, run:

npm run verify:small

This runs frontend and Vite-config TypeScript checking followed by the unit suite. Both npm test and verify:small deliberately exclude financing-submission-permissions.test.ts, because that credential-gated integration test writes a financing log row and is not safe routine validation. Only the dedicated test:integration:financing runner supplies its ephemeral write opt-in; do not persist that internal marker in an environment file.

Server changes require an additional scoped check:

# Vercel API: syntax-check JavaScript and typecheck every TypeScript entry
npm run verify:api

# One or more changed Supabase Edge Function entry points
npm run typecheck:edge -- supabase/functions/<function-name>/index.ts

# Every function entry point (CI)
npm run typecheck:edge -- --all

The Edge command fails when no entry point is supplied, rejects paths outside supabase/functions, pins Deno 2.9.5, accepts multiple changed TypeScript paths or --all, disables local node_modules materialization, and checks the dedicated tracked supabase/functions/deno.lock in frozen mode. Runtime resolution still uses supabase/functions/deno.json; typecheck adds --import-map supabase/functions/deno.check.json and --no-remote so HTTPS esm.sh / deno.land specifiers resolve to locked npm: packages or the small local serve / xhr stand-ins. A new HTTPS import without a remap, a remap that still points at the network, or a remote that slips past the import map, fails instead of being skipped. A dependency change therefore fails until its reviewed lockfile update is committed. Pair each scoped checker with the relevant focused tests. Running npm run test:integration:financing is itself the per-run write opt-in and requires separate authorization, an approved target, and both test credentials in the invoking environment or ignored .env.local; the runner loads that local file before its credential preflight and fails before Vitest if either value is absent. It is never implied by npm test or verify:small.

To run one unit test file directly:

npx vitest run path/to/file.test.ts

npm run build is the full release/content pipeline, not the routine small-change check. Its lifecycle regenerates and validates many content artifacts, fetches live Google Places data, and runs scripts/indexnow-ping.mjs in postbuild. Treat it as release-adjacent external work and require the same authorization as a production trigger.

Generated artifacts

Do not hand-edit files marked as generated. Change the owning source or generator, run the relevant generate:*, rewrite:agent-urls, or other named generator script from package.json, and review the resulting diff before committing it.

For PCOC blog referrals, run npm run reconcile:blog-pcoc-referrals after editing or importing copy, then regenerate the blog index and Markdown twins. This incremental generator preserves the current article blocks, including corrections since the one-shot Wave 1 import. It adds the localized MyBoatCard referral paragraph and repairs the verified stale Transport Canada destinations; the Wave 1 importer also runs it. Edit the referral and URL rules in scripts/reconcile-blog-pcoc-referrals.mjs, rather than hand-editing its generated offer paragraphs. npm run check:blog-pcoc-referrals checks every language, scheduled/pilot articles and the archive; prebuild and Blog content integrity CI reject an operator-card reference without a clickable HBW referral, HARRIS15 and 15% in the same visible paragraph. Working official citations remain separate. The offer was verified on HBW's rental page on October 4, 2026; provider pricing and checkout acceptance are outside this editorial check.

Environment and secrets

• The tracked .env is public-only.
• Private local overrides belong in .env.local; *.local is already ignored.
• Keep secrets in Vercel or Supabase secret storage. Never paste them into shell history, documentation, commits, issues, logs, or model-worker prompts.

Inventory sync safety

Inventory is synced directly from Lightspeed DMS (the mercury_motor_inventory view). The public quote builder must not invoke sync-lightspeed-inventory.

For a manual sync, use the authenticated admin Stock Sync or inventory dashboard. Never put an internal secret in frontend code or paste a service-role key into a local curl.

Nightly Lightspeed sync remains a server-side scheduler concern. Changing Edge Function auth or cron is a separate production configuration change.

Inventory sync is production-adjacent. Do not document service-role keys, bearer tokens, customer-private data, or copy-and-paste production requests in this repository. Any manual production trigger or write requires explicit authorization and must use approved stored-secret tooling.