@helyx/bot 1.3.0 → 1.4.0

package/documentation/runbooks/installation-and-upgrades.md

@@ -1,54 +1,124 @@
 # Installation and upgrade runbook
 
-Use this runbook for the first start of a generated project and for a reviewed
-release-set update that preserves the local environment and database.
+Use this runbook from the root of a generated Helyx project. It covers first
+start, compatible release-set updates and failed validation.
+
+## Check the release boundary first
+
+This release uses consolidated fresh-install migration baselines. An existing
+database with the earlier migration chain cannot use those baselines as an
+ordinary in-place upgrade. Keep its matching packages and data and
+[contact Helyx support](../guides/privacy-and-support.md#contact-support-safely)
+before proceeding; no approved old-database transition is available yet.
+Do not reset a database, remove its migration
+history or change recorded checksums to make an update pass.
+
+The updater changes project metadata; it does not verify or provide a
+data-preserving migration path. A release described as fresh-install/reset-only
+must not be applied to an existing database through the ordinary update steps
+below.
 
 ## First installation
 
-1. Generate the project with `helyx self-host init` and a reviewed build
-   manifest.
-2. Copy and complete `.env` with `helyx setup`.
-3. Install dependencies with `npm ci` if they were not installed during
-   generation.
-4. Run `npm run doctor` and resolve every error.
-5. Start the process and confirm database, Discord, and module health.
-6. Exercise one low-risk command in a test server before production use.
+1. Download a starter ZIP, or generate it from the builder's reviewed manifest.
+2. Install its dependencies with `npm ci` unless generation used `--install`.
+3. Run `npm run setup`, then complete `.env`. A managed host may supply the
+   required values through its protected variables panel instead. Keep the
+   generated encryption key stable.
+4. Make the selected database reachable and run doctor through the matching
+   runtime path below. Resolve every error.
+5. Start Helyx and confirm database, Discord and module readiness. Exercise one
+   low-risk command in a private test server before production use.
+
+The starter uses compiled npm packages: direct Node.js operation has no local
+`npm run build` step. Docker builds the supplied image.
+
+## Run doctor in the right environment
+
+- **Direct Node.js:** run `npm run doctor` after installation and configuration.
+- **Docker Compose:** run `docker compose build bot`, start the included
+  PostgreSQL service with `docker compose up -d --wait database` if present,
+  then run
+  `docker compose run --rm bot node node_modules/@helyx/cli/dist/cli.js doctor`.
+  The MySQL Compose starter has no database service; its external database must
+  already be reachable. Use container doctor with container database addresses
+  such as `database`; that hostname normally cannot resolve from the host shell.
+- **Managed hosting:** install the pinned dependencies, supply the production
+  variables and run `npm run doctor` through the provider's console or one-off
+  command facility before enabling its start process.
+
+Doctor does not sign in to Discord, change the database or probe required server
+capabilities. It inspects core migration history and validates selected packages
+and engine compatibility. Module migration inspection runs only after no core
+migrations remain pending. On a fresh database, pending migrations are expected;
+normal startup applies core migrations, then module migrations, and probes
+database capabilities. `npm run migrate` applies core migrations only and is not
+a prerequisite before every start.
 
 ## Upgrade
 
-1. Read the release notes and confirm the supported Node.js and npm versions.
-2. Create a current PostgreSQL backup and preserve the existing project
+1. Read the release notes, confirm an ordinary upgrade is supported from your
+   installed database state, and check the supported Node.js and npm versions.
+2. Create a current backup of the selected database and preserve the existing project
    metadata and environment file.
-3. Stop the Helyx process cleanly.
+3. Stop the bot cleanly. With Compose use `docker compose stop bot`, preserving
+   the database service and volume; on a managed host stop its application process.
 4. Preview the compatible release set:
 
    ```sh
-   helyx self-host update --check
+   npm run update:check
    ```
 
 5. Apply it only after reviewing the complete change:
 
    ```sh
-   helyx self-host update --confirm
-   npm ci
-   npm run doctor
+   npm run update
    ```
 
-6. Start Helyx and verify health, command availability, and one representative
-   workflow for every upgraded module.
-
-The updater backs up managed project metadata under `.helyx/backups` and does
-not change `.env` or customer database data. Database migrations can be
-forward-only. Never edit migration history or downgrade individual Helyx
-packages to simulate a rollback.
+   The generated `update` script runs `helyx self-host update --confirm` followed
+   by `npm ci`. The CLI command alone does not install the refreshed dependency
+   set. Older starters without these scripts can use
+   `npx --yes @helyx/cli@latest self-host update --check`, then the same command
+   with `--confirm`, followed by `npm ci`.
+
+6. Run doctor through the runtime path above. Docker users must rebuild the bot
+   image first, then recreate it with `docker compose up -d bot` after doctor
+   passes. Direct Node.js users start with `npm start`; managed hosts use their
+   configured start command.
+7. Verify health, command availability and one representative workflow for every
+   upgraded module.
+
+The updater backs up `.gitignore`, `package.json`, `package-lock.json`,
+`helyx.modules.json` and `SHA256SUMS` under `.helyx/backups/<timestamp>/`. It
+refreshes exact Helyx dependencies and the lockfile together, leaving `.env` and
+database data unchanged. This metadata backup is not a database backup or an
+installed-dependency snapshot.
+
+If metadata generation or lockfile validation fails inside `--confirm`, the
+updater restores those managed files. That restoration does not cover a later
+`npm ci`, doctor or startup failure. Database migrations can be forward-only.
+Never downgrade individual Helyx packages to simulate a rollback.
+
+`DATABASE_ENGINE` defaults to `postgresql`; use `mysql` only with the matching
+adapter, database and module support. The setting is not a data-conversion tool.
+Keep the selected engine unchanged during an ordinary update. Missing adapters,
+an unsupported module/engine combination or an installation engine mismatch must
+be resolved explicitly, not bypassed by falling back to another adapter.
+
+Applied checksum mismatches or an interrupted MySQL DDL receipt are errors to
+investigate before restarting, not fresh-install pending notices.
 
 ## Failed validation
 
 Leave the process stopped, retain sanitised logs, and determine whether the
 failure is configuration, package integrity, database connectivity, or module
-compatibility. If the updater restored managed files, rerun `npm ci` and
-`npm run doctor` before restarting the previous version. Restore data only from
-a tested backup and only when the incident specifically requires it.
+compatibility. If the updater restored managed files before startup, rerun
+`npm ci` and doctor against that restored set; Docker users rebuild and validate
+the corresponding image. If startup or a manual migration already changed the
+database, restoring project files does not reverse those changes. Check
+package/schema compatibility and the backup recovery plan before restarting an
+older release. Restore data only from a tested compatible backup when the
+incident requires it.
 
 ## Troubleshooting
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@helyx/bot",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "Production Discord runtime for the modular Helyx platform.",
   "keywords": [
     "helyx",
@@ -25,7 +25,7 @@
   },
   "publishConfig": {
     "access": "public",
-    "provenance": true
+    "provenance": false
   },
   "type": "module",
   "files": [
@@ -50,27 +50,31 @@
     "start": "node --env-file-if-exists=../../.env dist/index.js"
   },
   "dependencies": {
-    "@helyx/config": ">=1.0.0 <2.0.0",
-    "@helyx/control-protocol": ">=0.5.0 <0.6.0",
-    "@helyx/core": ">=0.1.0 <0.2.0",
-    "@helyx/database": ">=2.0.0 <3.0.0",
-    "@helyx/framework": ">=0.1.0 <0.2.0",
-    "@helyx/module-manifest": ">=0.11.0 <0.12.0",
-    "@helyx/platform": ">=1.0.0 <2.0.0",
-    "@helyx/sdk": ">=0.13.0 <0.14.0",
-    "@helyx/status-client": ">=0.2.0 <0.3.0",
-    "@helyx/verification-contracts": ">=0.3.0 <0.4.0",
+    "@helyx/config": ">=1.4.0 <2.0.0",
+    "@helyx/control-protocol": ">=0.7.0 <0.8.0",
+    "@helyx/core": ">=0.2.0 <0.3.0",
+    "@helyx/database": ">=2.4.0 <3.0.0",
+    "@helyx/database-contracts": ">=0.2.0 <0.3.0",
+    "@helyx/framework": ">=0.2.0 <0.3.0",
+    "@helyx/module-manifest": ">=0.13.0 <0.14.0",
+    "@helyx/platform": ">=1.3.0 <2.0.0",
+    "@helyx/sdk": ">=0.15.0 <0.16.0",
+    "@helyx/status-client": ">=0.3.0 <0.4.0",
+    "@helyx/verification-contracts": ">=0.4.0 <0.5.0",
     "discord.js": "14.27.0",
-    "fastify": "5.12.3",
+    "fastify": "5.12.7",
     "pino": "10.3.1",
     "redis": "6.1.0",
-    "undici": "6.28.0",
+    "undici": "6.29.0",
     "ws": "8.21.1",
     "zod": "4.4.3"
   },
+  "optionalDependencies": {
+    "@helyx/database-mysql": ">=0.2.0 <0.3.0"
+  },
   "peerDependencies": {
-    "@helyx/module-automod": ">=1.0.0 <2.0.0",
-    "@helyx/module-moderation": ">=1.0.0 <2.0.0"
+    "@helyx/module-automod": ">=1.1.0 <2.0.0",
+    "@helyx/module-moderation": ">=1.1.0 <2.0.0"
   },
   "peerDependenciesMeta": {
     "@helyx/module-automod": {