@helyx/bot 1.3.1 → 1.5.0

package/documentation/runbooks/backup-and-recovery.md

@@ -1,14 +1,15 @@
 # Backup and recovery runbook
 
-A usable Helyx backup includes PostgreSQL plus the environment and generated
+A usable Helyx backup includes the selected PostgreSQL or MySQL-compatible database plus the environment and generated
 key material required to read encrypted records. A copy of the generated
 project without its database is not a complete backup.
 
 ## Back up
 
-1. Record the installed package lockfile and Helyx release versions.
-2. Create a consistent PostgreSQL backup with your database provider or
-   PostgreSQL tooling.
+1. Preserve `package.json`, `package-lock.json`, `helyx.modules.json` and the
+   matching Helyx release versions. Record the selected database engine.
+2. Create a consistent backup with your database provider or the appropriate
+   engine-specific tooling.
 3. Back up `.env` and generated enrollment or encryption material separately.
 4. Encrypt backups, restrict access, and store at least one copy away from the
    running host.
@@ -25,14 +26,32 @@ At a regular interval:
 2. Restore a selected backup without overwriting production.
 3. Restore the matching environment and key material through the host's secret
    mechanism.
-4. Run `npm ci` and `npm run doctor`.
-5. Confirm a stateful module can read its configuration and records.
+4. Restore the matching project metadata and install that exact release with
+   `npm ci`, or build its Docker image. Run doctor in the disposable environment;
+   Compose users run
+   `docker compose run --rm bot node node_modules/@helyx/cli/dist/cli.js doctor`.
+5. Start the restored bot only with an explicitly authorised test Discord
+   identity and private server. Do not run a second copy with the active bot's
+   token. Confirm a stateful module can read its configuration and records.
 6. Destroy the disposable environment using the same controls as production.
 
 Record the recovery time, the backup generation used, the checks performed,
 and any corrective action. Treat restored data with the same access controls
 and deletion obligations as production data.
 
+Restore into the same database engine with compatible server capabilities.
+Changing `DATABASE_ENGINE` selects an adapter; it does not convert a dump, schema
+or existing installation from PostgreSQL to MySQL or the reverse. Preserve the
+engine identity and migration receipts together with the data.
+
+Use the packages that match the backup's migration history. The current
+fresh-install baselines are not an upgrade path for an older restored database.
+[Contact Helyx support](../guides/privacy-and-support.md#contact-support-safely)
+before attempting that transition; no approved procedure is available yet.
+An updater backup under `.helyx/backups` contains managed project metadata only;
+it cannot restore database contents, encryption keys, container images or
+installed `node_modules`.
+
 ## Incident recovery
 
 Stop writes before a destructive restore. Preserve evidence needed to
@@ -42,7 +61,7 @@ restore over the only production database.
 
 ## Troubleshooting
 
-### PostgreSQL restored but Cloud Connect or protected records fail
+### The database restored but Cloud Connect or protected records fail
 
 Confirm the restored runtime uses the matching data-encryption key and any
 generated enrolment material. Do not replace the key or delete affected rows to

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.1",
+  "version": "1.5.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.3.0",
-    "@helyx/framework": ">=0.1.0 <0.2.0",
-    "@helyx/module-manifest": ">=0.11.0 <0.12.0",
-    "@helyx/platform": ">=1.2.0",
-    "@helyx/sdk": ">=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.8.0 <0.9.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.16.0 <0.17.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.2",
-    "@helyx/module-moderation": ">=1.0.2"
+    "@helyx/module-automod": ">=1.1.1 <2.0.0",
+    "@helyx/module-moderation": ">=1.1.1 <2.0.0"
   },
   "peerDependenciesMeta": {
     "@helyx/module-automod": {