HiveGrid-Wireframes/hivegrid-cloud/docs/upgrades.md

Upgrade Runbook

Purpose

This entrypoint defines the safe path for dependency, runtime, database, provider, and deployment-adjacent upgrades in the boilerplate. Use it before changing package versions, Node/Corepack behavior, Prisma migrations, React Router runtime assumptions, worker Redis settings, Mailjet configuration, or security-sensitive provider boundaries.

This guide intentionally links to the deeper contracts instead of duplicating them:

• docs/porting-guide.md for current boilerplate naming, runtime status, package-manager wording, and manual browser/E2E policy.
• docs/porting-verification.md for the post-port documentation checklist and supported non-E2E verification posture.
• docs/database.md for PostgreSQL, Prisma, migration status, deployment, backup, restore, and redacted database diagnostics.
• docs/deployment.md for image, Coolify, rollback, health, and manual runtime verification boundaries.
• docs/security.md for headers, CORS, authentication, Mailjet, secret redaction, and incident-response constraints.

Package manager and runtime prerequisites

The repository is pinned to pnpm@10.33.0 through package.json. Do not replace upgrade instructions with unpinned npm, yarn, or scaffold-create examples. Prepare local and CI environments with Corepack before installing or comparing dependency changes:

corepack enable
corepack prepare pnpm@10.33.0 --activate
pnpm install

The active web runtime is the @toolctrl/web React Router application in apps/web/app, with root scripts delegating to it. apps/api is the Hono API foundation, apps/worker is opt-in worker infrastructure, and selected packages/* surfaces are package boundaries with different levels of runtime wiring. Confirm those statuses against docs/porting-guide.md before writing upgrade notes that imply extraction is complete.

Dependency upgrade workflow

1. Read the package-manager pin in package.json and keep the same command family for all examples.
2. Review the dependency change set for runtime-sensitive packages: React Router, React, Prisma, PostgreSQL adapters, Mailjet/mail packages, Redis/BullMQ, Hono/API packages, security/header/CORS packages, and build tooling.
3. Install with the pinned pnpm version and keep lockfile changes tied to the reviewed package update.
4. Run focused static checks before any manual runtime inspection:

pnpm run typecheck
pnpm run lint
pnpm run verify:production-docs
pnpm run verify:docs-links
pnpm exec vitest run scripts/verify-production-docs.test.mjs scripts/docs-link-check.test.ts

Use additional scoped Vitest files when the upgraded package has direct test coverage. Do not replace these checks with broad browser automation or live provider checks during Auto-Mode execution.

Prisma and database migration checks

Database-affecting upgrades include Prisma packages, PostgreSQL adapter changes, generated-client changes, and schema or migration edits. Follow docs/database.md for the detailed operations contract.

Safe upgrade expectations:

• Confirm DATABASE_URL and DIRECT_URL only as environment key names; never paste raw values into documentation, tickets, logs, screenshots, or verification summaries.
• Use pnpm run typecheck when generated types or Prisma client artifacts could drift.
• Use pnpm run verify:production-docs and pnpm run verify:docs-links after documentation changes that describe database behavior.
• Treat pnpm run db:migrate:deploy as the approved migration deployment command, not as a local authoring command.
• Confirm backup or restore-point readiness through the environment-owned process before production migration deployment.

Local Prisma authoring commands documented in docs/database.md remain local-only and must not be copied into production automation.

React Router and runtime checks

React Router, React, Vite/build tooling, route behavior, headers, or server-runtime upgrades require explicit attention to the current @toolctrl/web runtime:

• Keep apps/web/app as the authoritative web source tree, with root scripts as command entrypoints, unless a later verified extraction changes that fact.
• Keep apps/web described as the runtime boundary and package owner for web code.
• Use pnpm run typecheck, pnpm run lint, and scoped Vitest commands for affected route or runtime tests.
• Use docs/deployment.md for health, readiness, image, and rollback expectations.

Browser, Playwright, Cypress, and other E2E checks are manual runtime activities unless a human explicitly approves the exact focused run. Upgrade documentation may describe the manual scenario to review, but it must not claim automatic browser/E2E execution.

Worker, Redis, and queue opt-in checks

Worker-related upgrades include BullMQ, Redis clients, queue contracts, worker build output, and packages consumed by apps/worker. The worker remains opt-in and Redis-backed:

• WORKER_ENABLED=true is required to enable worker execution.
• BULLMQ_REDIS_URL is the primary Redis queue configuration key; REDIS_URL may appear as a platform-binding fallback where documented.
• Health and readiness output may include enablement state, queue names, failed-job counts, and redacted dependency codes.
• Logs and docs must not include Redis URLs, passwords, raw job payloads, tenant identifiers, or customer data.

Use scoped package or Vitest checks for worker code changes. Keep live queue replay, live Redis inspection, and container runtime checks in the manual operations boundary unless explicitly approved.

Mailjet and security review

Mailjet is the active transactional mail boundary. Mail or provider upgrades must preserve the contract in docs/security.md:

• MAILJET_API_KEY and MAILJET_FROM_EMAIL are configuration key names only, not values to print.
• Webhook handling must continue to verify signing before trusting provider events.
• Diagnostics may record provider category, event type label, delivery status, request ID, job ID, and whether signature verification passed.
• Documentation, tickets, and logs must not include API keys, webhook signing secrets, provider payloads, customer email addresses, message bodies, bearer tokens, cookies, or dashboard screenshots containing personal data.

Security-sensitive upgrades also require reviewing headers, CORS, API authentication, request-id correlation, and secret redaction in docs/security.md.

Rollback notes

Rollback planning is required before production-facing upgrades:

1. Identify the previous known-good package or image state.
2. For deployable images, use immutable SHA-derived tags as described in docs/deployment.md; do not rely on mutable guesses.
3. For database migrations, confirm backup or restore-point availability before deployment and preserve only redacted evidence in the incident record.
4. For worker incidents, pause or drain queues through approved operational tooling before replaying jobs.
5. Record rollback evidence with target name, tag or reviewed version, status, request ID, job ID, and redacted diagnostic code only.

If rollback output exposes raw secrets, connection strings, UUID-like deployment endpoints, provider tokens, stack traces with credentials, tenant identifiers, or customer data, treat it as a secret exposure and follow the containment guidance in docs/security.md.

Documentation verification and link safety

After changing upgrade documentation or any linked production runbook, run the non-E2E documentation gates:

pnpm run verify:production-docs
pnpm run verify:docs-links
pnpm exec vitest run scripts/verify-production-docs.test.mjs scripts/docs-link-check.test.ts

These checks should report file-scoped failures for missing documents, forbidden placeholders, forbidden automatic browser/E2E commands, broken local paths, and broken local anchors. They do not require external network access and must not expose secrets.

Upgrade review checklist

• Package-manager examples use Corepack and pinned pnpm@10.33.0.
• Commands are limited to scripts present in package.json or explicit scoped Vitest examples.
• Database changes follow PostgreSQL and Prisma guidance in docs/database.md.
• React Router remains documented as the active @toolctrl/web runtime in apps/web/app.
• Worker and Redis behavior stays opt-in through documented environment key names.
• Mailjet and security-sensitive provider changes preserve signing, auth, header, CORS, and redaction boundaries.
• Rollback notes use immutable image tags, reviewed versions, backups, and redacted diagnostics.
• Browser, Playwright, Cypress, live Docker, live registry, Coolify, and provider-console checks are manual unless the exact run is explicitly approved.
• No raw secrets, production credentials, tenant identifiers, customer data, provider payloads, or secret-shaped examples were added.
• pnpm run verify:production-docs, pnpm run verify:docs-links, and relevant scoped Vitest checks pass before closing the upgrade documentation change.