deckhearth/.convoys/fix-reset-db-script.md

fix-reset-db-script (P2 hygiene — fold of two queued follow-ups)

Status: RESOLVED 2026-05-26 (PR #25, squash commit 3ab9bf8) Priority: P2 hygiene (not a security blocker; npm run reset-db is dev-only and currently broken on Node 22, so blast radius is low — but the bug pattern is the same as the P0-grade weak-creds shape that drop-public-setup already fixed once) Convoy owner: parent (no architect — fold of two well-scoped follow-ups; single-file fix following an established proven pattern) Opened: 2026-05-25 Merged: 2026-05-26

Problem (3 bugs in 1 file)

scripts/reset-db.js carries three known bugs surfaced by the pick-a-name architect audit (2026-05-24) and ratified for fix in this session:

1. CJS-in-ESM environment (lines 10, 12, 142): require() calls in an ESM file (package.json "type": "module" since bump-next-js). npm run reset-db throws ReferenceError: require is not defined on Node 22.x. Same bug pattern that hit setup-neon-db.js pre-drop-public-setup Brief 2. Fix is the same fix.
2. Hardcoded weak admin password (line 143: bcrypt.hash('admin123', 12)): identical anti-pattern to the one drop-public-setup Brief 1 removed from setup-neon-db.js. Should require ADMIN_INITIAL_PASSWORD env var, fail loud if unset.
3. Password echoed to stdout (line 156: console.log(' Admin Password: admin123')): explicit security anti-pattern. setup-neon-db.js post-drop-public-setup does NOT echo the password — same convention applies here.

Fix (mirror setup-neon-db.js exactly)

The fix shape is fully derived from the post-drop-public-setup scripts/setup-neon-db.js file shipped at b63b509. Verbatim mirror:

• Replace CJS require('dotenv').config() with ESM import dotenv from 'dotenv'; dotenv.config({ path: '.env.local' })
• Replace CJS const { neon } = require('@neondatabase/serverless') with ESM import { neon } from '@neondatabase/serverless'
• Replace inline CJS const bcrypt = require('bcryptjs') (line 142) with top-level ESM import bcrypt from 'bcryptjs'
• Add the same fail-loud ADMIN_INITIAL_PASSWORD env-var check at the top of the async function resetDatabase() body, with the same helpful error message that points to README.md
• Replace bcrypt.hash('admin123', 12) with bcrypt.hash(adminPassword, 12)
• Update the admin email to the post-pick-a-name canonical (admin@deckhearth.com — already correct in the file at line 147, by the B2 sweep)
• Replace the Admin Password: admin123 log line with Admin user ready (email: admin@deckhearth.com) (matching setup-neon-db.js line 157)
• Add ON CONFLICT (email) DO NOTHING to the INSERT (matching setup-neon-db.js line 149 — defensive against double-run)

Scope

• In scope: scripts/reset-db.js only.
• Out of scope: any other scripts/*.js files (none have the same bugs — setup-neon-db.js already fixed, migration script already ESM, the rest don't ship admin creds).

Why no architect

This is a proven-pattern fold — both convert-reset-db-to-esm and purge-weak-creds-from-helpers were architect-recommended in pick-a-name for "may fold if more such bugs accumulate in helper scripts." All 3 bugs are in 1 file; the fix shape is verbatim-mirror of the post-drop-public-setup setup-neon-db.js. No new decisions; no new precedents; no surface for an architect to add value. Parent applies the fix, runs the bounded checks, opens the PR. If anything surprising surfaces (a 4th bug, a different bcrypt API, etc.), the parent stops and dispatches an architect mid-execution.

Acceptance criteria

• node --check scripts/reset-db.js exit 0
• npm run lint exit 1 with 128 problems (baseline preserved; no regression)
• npm run test:run 21/21 pass (no test surface touched; verification only)
• Grep: 0 occurrences of require( in scripts/reset-db.js
• Grep: 0 occurrences of admin123 in scripts/reset-db.js
• Grep: 0 occurrences of Admin Password in scripts/reset-db.js
• Grep: ADMIN_INITIAL_PASSWORD referenced (1 hit)

Operator action required pre-merge

• None pre-merge (no schema change, no env-var addition).
• Optional post-merge: if the operator wants to verify the fix works end-to-end, they can run npm run reset-db against a non-prod Neon branch (the script drops all tables — DO NOT run against prod). The script will refuse to run if ADMIN_INITIAL_PASSWORD is not set in .env.local, with the same helpful error message setup-neon-db.js already uses.

Known constraints

• The script is destructive (drops all tables). We do NOT live-test it in this convoy. Boot-the-brief is syntax + lint + vitest only. Live verification is the operator's optional post-merge action.
• This convoy does NOT add ESLint no-restricted-syntax rule against CJS require() in scripts/**. That would be a separate lint-against-cjs-in-esm-scripts convoy. Surfaced here so future helper scripts don't re-introduce the bug.

Out of scope (queued follow-ups)

• lint-against-cjs-in-esm-scripts (NEW, P3 polish): add ESLint rule to prevent any future require() in scripts/** once package.json has "type": "module".
• add-neon-return-shape-rule (P3 polish, surfaced 2026-05-25 by PR #24): codify the neon() vs @vercel/postgres return-shape difference as a rule. May fold into single-sql-client which would eliminate the dual-client problem entirely.

Owns

Parent (single-file proven-pattern fix; no architect or implementer subagent required).

As-shipped

Single squash commit 3ab9bf8 (PR #25, merged 2026-05-26). Parent-owned end-to-end per the convoy spec — no architect, no implementer subagent dispatched. Mirror-the-pattern fix exactly as planned; no mid-execution surprises that would have forced an architect bounce.

Diff: 2 files, +161 / -18. scripts/reset-db.js +55 / -18 (the actual fix); .convoys/fix-reset-db-script.md +124 (the planning document, committed atomically with the fix).

The three bugs, atomically resolved:

1. CJS-in-ESM (was lines 10, 12, 142): three require() calls replaced by ESM top-level imports (import dotenv from 'dotenv', import { neon } from '@neondatabase/serverless', import bcrypt from 'bcryptjs'). npm run reset-db now executes on Node 22.x instead of throwing ReferenceError: require is not defined.
2. Hardcoded weak admin password (was line 143): replaced bcrypt.hash('admin123', 12) with bcrypt.hash(adminPassword, 12), where adminPassword is read from process.env.ADMIN_INITIAL_PASSWORD with a fail-loud check at the top of resetDatabase(). The check exits with code 1 BEFORE opening any DB connection, matching setup-neon-db.js's post-drop-public-setup shape verbatim.
3. Password echoed to stdout (was line 156): replaced the console.log(' Admin Password: admin123') line with console.log(' Admin user ready (email: admin@deckhearth.com)') — exactly the line setup-neon-db.js line 157 uses post-DPS.

Bonus defensive shape: the seed INSERT now uses ON CONFLICT (email) DO NOTHING (matching setup-neon-db.js line 149) so a double-run doesn't error on the existing admin row. This is defensive only; the convoy is destructive (drops all tables first), so the only realistic "existing admin row" scenario is operator confusion between setup-db and reset-db.

Verification (all gates green at merge):

• node --check scripts/reset-db.js → exit 0
• npm run lint → 128 problems (baseline preserved, no regression)
• npm run test:run → 21/21 pass
• Grep scripts/reset-db.js: 0 require( | 0 admin123 | 0 'Admin Password' | 3 ADMIN_INITIAL_PASSWORD references (docstring + const
  • error msg)
• CI on PR #25: Lint ✓ (39s) | Vitest 21/21 ✓ (28s) | Playwright smoke 3/3 ✓ (1m5s) | forbidden-endpoints ✓ (5s) | forbidden-cors-headers ✓ (4s) | Vercel preview deploy ✓ | Aggregate gate ✓
• Screenshot diff: not triggered (script-only PR — paths: filter excludes scripts/**, so the queued tighten-visual-diff-path-filter follow-up correctly did NOT fire here)

Live verification deferred per convoy spec. The script is destructive (drops all tables); we did not exercise it against a Neon branch in this convoy. If the operator wants end-to-end proof, the optional post-merge action is npm run reset-db against a throwaway Neon branch with ADMIN_INITIAL_PASSWORD set (and verify that unsetting it triggers the fail-loud exit with the helpful error message).

Cross-validation finding (organic, not a planned AC). The Playwright smoke 3/3 PASS on a script-only PR confirms that adopt-playwright-smoke's smoke spec is correctly insensitive to scripts/** edits — the deployed preview is unaffected by changes to dev-only utility scripts, and the smoke spec correctly green-lights the deployment. This is the fifth consecutive convoy where the same 3-test smoke spec has defended the auth surface (PR #15 Layout default-user → PR #19 CORS-tighten → PR #20 rate-limiting → PR #21 pick-a-name → PR #25 reset-db-fix) without anyone writing a dedicated test.

Operator action required going forward: none. No new env vars (ADMIN_INITIAL_PASSWORD was already required by setup-neon-db.js post-drop-public-setup; this convoy adds nothing new to the env contract). No schema change. No infra change.

Surfaced follow-up (newly queued): lint-against-cjs-in-esm-scripts (P3 polish) — add an ESLint no-restricted-syntax rule against require( calls in scripts/** once package.json has "type": "module". Would have caught both this convoy AND the drop-public-setup Brief 2 bug at lint time. Filed in .convoys/ship-readiness.md § Queued convoys.

purge-weak-creds-from-helpers scope reduction. This convoy satisfies the scripts/reset-db.js portion of the queued purge-weak-creds-from-helpers follow-up. Remaining scope of that queued convoy: scripts/create-test-users.js (alice/bob test fixtures) and TESTING_GUIDE.md (documents the weak creds). Both are out of scope here per the convoy spec's single-file boundary.