Improve logging and add guardrails for seed/dev scripts

[diyor28]

Problem

Our seed / dev scripts are currently too easy to misuse and provide poor feedback when something goes wrong. This leads to confusion (e.g., running seeds against a restored backup or wrong environment) and time wasted debugging.

Goals

1. Human-friendly logging

   • Clear, structured logs for each step (connect DB, migrate, truncate, seed entities, etc.).
   • Highlight key context at startup: environment, DB host/name/user, schema, app version/commit (if available).
   • Distinguish INFO/WARN/ERROR and show actionable messages.

2. Guardrails / “fool-proof” behavior

   • Hard checks to prevent running destructive operations on non-dev environments.
   • Detect and warn/abort when targeting:
     • production / staging DBs
     • non-local hosts (unless explicitly allowed)
     • databases with large row counts / existing non-empty critical tables (configurable)
   • Require explicit confirmation for dangerous actions (truncate/reset) via:
     • --yes flag OR
     • interactive prompt (only if TTY)
   • Provide a dry-run mode (--dry-run) showing what would be executed.

3. Better CLI UX

   • Consistent flags and help output.
   • Exit codes that CI/dev tooling can rely on.

Acceptance Criteria

• Running the seed/dev scripts prints a concise, readable summary of what it will do and where.
• By default, scripts refuse to run destructive actions outside dev/local contexts.
• A user can override safeguards intentionally via explicit flags (documented).
• Logs include enough context to understand failures without digging into code.
• Documentation updated (README / docs) with examples.

Notes / Suggestions

• Consider using a structured logger (zap/zerolog/slog) with pretty console output in dev.
• Consider centralizing config validation/guard logic so all scripts share the same safety checks.

[Andor2025]

This is a really solid breakdown, and the goals make a lot of sense.

One thing we’ve seen in similar seed/dev workflows is that even with good guardrails and flags, people still get tripped up because the implicit context isn’t surfaced clearly enough.

Not just “what will run”, but:

• what assumptions are being made about the environment
• what state the system believes it’s in (fresh DB vs restored vs partially seeded)
• and why a given action is considered dangerous right now

In practice, the biggest reduction in misuse came when scripts treated this like a stateful interaction:
explicitly summarizing the inferred context up front (env, data volume, prior runs, risk level), and making the user acknowledge that mental model before proceeding — not just the action itself.

Out of curiosity: do these scripts currently persist or infer anything about prior runs / database state, or is each execution treated as fully stateless?

[diyor28]

This is a really solid breakdown, and the goals make a lot of sense.

One thing we’ve seen in similar seed/dev workflows is that even with good guardrails and flags, people still get tripped up because the implicit context isn’t surfaced clearly enough.

Not just “what will run”, but:

• what assumptions are being made about the environment
• what state the system believes it’s in (fresh DB vs restored vs partially seeded)
• and why a given action is considered dangerous right now

In practice, the biggest reduction in misuse came when scripts treated this like a stateful interaction: explicitly summarizing the inferred context up front (env, data volume, prior runs, risk level), and making the user acknowledge that mental model before proceeding — not just the action itself.

Out of curiosity: do these scripts currently persist or infer anything about prior runs / database state, or is each execution treated as fully stateless?

Don't spam AI slop