# Release Checklist

Use this checklist before replacing the live CRM code.

Review `RELEASE_NOTES.md` and `DATA_MIGRATION_GUIDE.md` before packaging so the included modules, removed modules, and data handling steps are clear.

## 1. Backup Live State

- Back up the live SQLite database from `server/db/office365.sqlite`.
- Back up the live `.env` or cPanel environment variables.
- Keep a copy of the currently deployed application folder or archive.

## 2. Verify Locally

Confirm the machine uses Node.js 20+ and npm 10+ before installing or packaging.

Run:

```bash
npm run smoke:local
npm run preflight:production
npm run scan:secrets
npm run release:audit
npm run release:package
npm run release:checksum
npm run release:cleanup-report
npm run release:status
```

These must pass before upload. The smoke check starts the app against a temporary SQLite database and verifies `/api/health` plus site content. The preflight check verifies runtime versions, required files, and built frontend assets. The secret scan catches accidental credentials in source files. The audit command reports local non-release artifacts without deleting them. The package command runs tests, builds the frontend, writes `RELEASE_MANIFEST.json`, creates a deployable archive under `releases/`, writes a `.sha256` checksum file, writes a `.handoff.md` deployment note, and validates the archive contents. The checksum command independently verifies the latest archive against its `.sha256` file. The cleanup report lists older local release archives for manual review without deleting them. The status command prints the latest archive path, size, SHA-256 hash, checksum file, handoff note, and audit counts for handoff.

## 3. Package Source

Do not package or upload:

- `node_modules`
- `.env`
- `server/db/*.sqlite`
- `server/db/*.sqlite-wal`
- `server/db/*.sqlite-shm`
- old patch ZIP/TAR archives
- local test files
- one-off historical reconciliation/import scripts

The built frontend must exist in `server/public` after `npm run verify:production`.
Review `RELEASE_MANIFEST.json` to confirm the built public artifacts were generated.
Upload the generated archive from `releases/`, then extract it into the deployment folder.
Do not upload an archive unless `release:validate` passes.
Use `release:audit` to review local runtime files and historical patch archives before handoff.
Use `release:status` to capture the final archive name and SHA-256 hash.
Upload the matching `.sha256` file with the release archive when possible.
Keep the generated `.handoff.md` note with the archive for deployment records.
After upload, run `npm run release:checksum -- releases/<archive-name>.tar.gz` or compare the uploaded archive with the `.sha256` file before extraction.

## 4. Server Environment

Confirm production values are set:

- Node.js 20+ selected in the hosting runtime
- npm 10+ available for install/build commands
- `NODE_ENV=production`
- `APP_URL`
- `CLIENT_ORIGIN`
- `DATABASE_PATH`
- `SESSION_SECRET`
- `SMTP_ENCRYPTION_KEY`
- `PASSWORD_RESET_SECRET`
- SMTP values or saved SMTP profiles
- Teams tenant/client values only if `TEAMS_ENABLED=true`

Keep secrets stable across releases unless intentionally rotating them.
Production startup and production preflight will fail if `SESSION_SECRET`, `SMTP_ENCRYPTION_KEY`, or `PASSWORD_RESET_SECRET` are missing, placeholder/default, or shorter than 32 characters.
If Teams integration is enabled, production preflight will also validate the Azure tenant ID, client ID, client secret, and redirect URI.

## 5. Install And Restart

On the server:

```bash
npm install --omit=dev
npm run preflight:production
npm run verify:production
```

Restart the Node.js app from cPanel or the process manager.

## 6. Smoke Test

Check:

- `https://your-domain.example/api/health` returns `ok: true`, `frontendReady: true`, and `databaseReady: true`.
- Public site loads.
- Admin login works.
- Leads page loads existing data.
- Sales page loads existing data.
- Invoice page opens and previews invoices.
- Reports download works according to user permissions.
- SMTP test works from Settings.
- New lead submission creates a CRM record and redirects correctly.

## 7. Rollback

Rollback means restoring:

- Previous application folder or release archive.
- Previous database backup if schema/data was changed.
- Previous environment values if they were changed.