@helyx/cli 1.2.3 → 1.4.1

package/templates/self-host/.env.example

@@ -10,7 +10,8 @@ DISCORD_CLIENT_ID=12345678901234567
 # requires message content and it is enabled in the Discord developer portal.
 HELYX_MESSAGE_CONTENT_ENABLED=false
 # Enhanced Auto Moderation stays inside this bot process. One worker is the
-# recommended default; increase only after measuring local CPU and memory.
+# recommended default (range 1-4); increase only after measuring CPU and memory.
+# Hosted scanning uses the separate Helyx Ecko service, not these settings.
 HELYX_AUTOMOD_EMBEDDED_WORKERS=1
 # Optional conservative queue overrides (hard ceilings: 5000 items, 64 MiB,
 # 100 items per server). Defaults are used when these remain commented.
@@ -18,13 +19,19 @@ HELYX_AUTOMOD_EMBEDDED_WORKERS=1
 # HELYX_AUTOMOD_EMBEDDED_QUEUE_BYTES=67108864
 # HELYX_AUTOMOD_EMBEDDED_QUEUE_ITEMS_PER_GUILD=100
 # HELYX_AUTOMOD_EMBEDDED_REFRESH_SECONDS=300
-# Enable only when member inspection modules are loaded and the Discord Server
-# Members Intent is enabled in the Discord developer portal.
+# Enable for loaded member workflows such as Welcome, Access Control or Levels,
+# with Server Members Intent also enabled in the Discord developer portal.
 HELYX_GUILD_MEMBERS_ENABLED=false
 # Database
 # Docker: keep the URL. Direct Node.js/managed hosting: use your provider URL.
+DATABASE_ENGINE=postgresql
 DATABASE_URL=postgresql://database:5432/helyx
 DATABASE_SSL=disable
+# Self-host startup applies pending migrations automatically (the default).
+# Hosted-only inspect mode is not a self-host setting; leave this commented.
+# HELYX_DATABASE_STARTUP_MODE=apply
+# Match your provider: disable=no TLS; require=TLS without certificate
+# verification; verify-full=TLS with certificate verification.
 
 # Included Docker database — both password values must match.
 PGUSER=helyx
@@ -51,8 +58,8 @@ LOG_LEVEL=info
 # SHARDING: OFF BY DEFAULT
 
 # `off` is the compatible self-host default. Keep shard-only values commented
-# in this mode; an empty value is still rejected as configured. Advanced local
-# self-hosting may use `auto` to obtain Discord's recommendation under one
+# in this mode; an empty value is still rejected as configured. MySQL must stay
+# off. Advanced PostgreSQL self-hosting may use `auto` under one
 # supervisor, or `fixed` with a deliberate total count. Local mode never needs
 # Redis. Coordinated multi-host self-hosting is outside the first release.
 HELYX_SHARD_MODE=off
@@ -80,18 +87,15 @@ HELYX_SHARD_MODE=off
 HELYX_HOSTED_MODERATION_ENABLED=false
 
 # Guild command writes remain off until explicitly enabled for known guild IDs.
+# For enabled-module server commands, set writes=true, retain allowlist scope,
+# add comma-separated Discord server IDs below, and use global mode platform-only.
+# See README.md before changing these defaults. Legacy mode still allows globals.
 HELYX_GUILD_COMMAND_WRITES_ENABLED=false
 HELYX_GUILD_COMMAND_WRITE_SCOPE=allowlist
 # HELYX_GUILD_COMMAND_RELEASE_ID=
 HELYX_GLOBAL_COMMAND_MODE=legacy
 # HELYX_GUILD_COMMAND_WRITE_GUILD_IDS=
 
-# Privacy tooling ships with self-hosted Helyx but stays disabled until the
-# dedicated least-privilege executor connection has been configured.
-HELYX_PRIVACY_ENABLED=false
-# HELYX_PRIVACY_EXECUTOR_DATABASE_URL=<dedicated-privacy-executor-postgresql-url>
-# HELYX_PRIVACY_EXECUTOR_DATABASE_SSL=disable
-
 # Alternative Cloud Connect enrolment — the Discord command is preferred
 # HELYX_CLOUD_ENROLMENT_TOKEN=replace-with-a-short-lived-enrolment-code
 # HELYX_CLOUD_ENROLMENT_FILE=./helyx.cloud-enrolment.json

package/templates/self-host/DOCUMENTATION.md

@@ -10,6 +10,12 @@ operator runbooks, and module-authoring instructions. It is replaced when the
 bot package is updated, so keep deployment-specific notes outside
 `node_modules`.
 
+Begin with this generated project's `README.md` to choose Node.js, Docker
+Compose or managed hosting. Use the installed runbooks for doctor, updates and
+backup/recovery; commands for a Helyx source checkout do not apply to this
+compiled-package starter. Check the release's fresh-install/upgrade boundary
+before using an existing database.
+
 The generated project's `.env.example` is the active configuration template.
 Never add the real `.env` file, credentials, database dumps, or private logs to
 a support bundle or source repository.

package/templates/self-host/Dockerfile

@@ -12,4 +12,4 @@ ENV NODE_ENV=production
 
 USER node
 
-CMD ["npm", "start"]
+CMD ["node", "node_modules/@helyx/cli/dist/cli.js", "start"]

package/templates/self-host/README.md

@@ -1,6 +1,6 @@
 # Helyx Self-Hosted starter
 
-This self-host starter was generated from the reviewed Helyx catalogue. It contains deployment configuration and exact npm dependencies, not Helyx source code or credentials.
+This self-host starter was generated from the reviewed Helyx catalogue. It contains deployment configuration and exact npm dependencies, not Helyx source code or credentials. Both PostgreSQL and MySQL-compatible database adapters are included; `DATABASE_ENGINE` selects the active adapter and defaults to `postgresql` when omitted.
 
 ## Selected modules
 
@@ -15,42 +15,81 @@ The matching offline operator and module-author documentation is listed in
 
 - A Discord application and bot token
 - One of the supported runtime paths below
-- PostgreSQL 17 or another currently supported PostgreSQL release, supplied by your chosen path
+- One supported PostgreSQL or MySQL-compatible database, supplied by your chosen path
 - A safe backup location for the database and this project's lockfile
 
 ## Choose a runtime path
 
 ### Node.js and PowerShell or another shell
 
-Use this path on a local machine or VPS without Docker. It requires Node.js `>=24 <27`, npm `>=11`, and a local or hosted PostgreSQL database. Helyx does not require Docker, but PostgreSQL remains mandatory.
+Use this path on a local machine or VPS without Docker. It requires Node.js `>=24 <27`, npm `>=11`, and one local or hosted supported database. Helyx does not require Docker.
 
 1. Run `npm ci`.
-2. Run `npm run setup`. Helyx creates `.env` from the supplied example and generates its private local data-encryption key. Repeating setup never replaces an existing key or configuration value.
-3. Edit `.env`, replace every placeholder and set `DATABASE_URL` for your PostgreSQL server.
+2. Run `npm run setup`. Helyx creates `.env` when needed and fills a missing, blank or example data-encryption key. It preserves other existing configuration and a non-placeholder key.
+3. Edit `.env`, replace every placeholder, set `DATABASE_ENGINE` to `postgresql` or `mysql`, and set the matching `DATABASE_URL`. Omitting `DATABASE_ENGINE` selects PostgreSQL.
 4. Set `DATABASE_SSL=disable` for a trusted local connection, or `require`/`verify-full` according to your database provider.
 5. Run `npm run doctor`.
 6. Run `npm start`.
 
+The starter uses compiled npm packages and has no local `npm run build` step.
+For this path, replace Docker-only addresses such as `database` with your
+reachable database hostname before running doctor.
+
+Percent-encode special characters in database URL credentials. Confirm the
+provider's actual TLS requirements before startup: `disable` uses no TLS,
+`require` encrypts the connection without verifying the server certificate, and
+`verify-full` also verifies the certificate. Prefer `verify-full` for a remote
+database when the provider's certificate is trusted; do not disable verification
+just to hide a connection error. A generated MySQL starter initially uses
+`require`, which is a template value, not proof of the provider's requirements.
+
 ### Docker Compose
 
 Use this path when Docker with Compose support is available. The included configuration runs both Helyx and PostgreSQL 17.
 
+Complete setup and credentials first. Before the start command below, run the
+container doctor preflight that follows the numbered steps; a host-shell doctor
+cannot normally resolve a container-only hostname such as `database`.
+
 1. Run `npm ci`, then `npm run setup`. This creates the local configuration and data-encryption key safely; the bot itself will still run in Docker.
 2. Edit `.env` and replace all placeholder credentials and passwords.
-3. Keep the supplied internal `DATABASE_URL` and `DATABASE_SSL=disable`.
+3. Keep `DATABASE_ENGINE=postgresql` with the supplied internal `DATABASE_URL` and `DATABASE_SSL=disable`.
 4. Run `docker compose up --build -d`.
 5. Review startup with `docker compose logs -f bot`.
 6. Stop services with `docker compose down`. Do not add `--volumes` unless you deliberately intend to delete the database volume.
 
+For the doctor preflight, build the bot image:
+
+```sh
+docker compose build bot
+```
+
+If the generated `compose.yaml` includes the PostgreSQL `database` service,
+start it with `docker compose up -d --wait database`. A MySQL starter has no
+database service; make its external database reachable instead. Then validate
+inside the bot image before starting it:
+
+```sh
+docker compose run --rm bot node node_modules/@helyx/cli/dist/cli.js doctor
+```
+
+The container starts the Helyx CLI directly through Node so Docker stop signals
+reach the bot's shutdown handlers. Local hosting still uses `npm start`.
+
 ### Managed bot hosting
 
-Use this path when a provider installs npm packages and runs the package start script for you. Configure `npm start` as the start command and supply every required variable through the provider's environment or variables panel. Use a PostgreSQL database reachable from that provider. A local `.env` file is not required when the host supplies the variables. Generate `HELYX_DATA_ENCRYPTION_KEY` once with `node -e "console.log(require('node:crypto').randomBytes(32).toString('base64'))"`, store it in the provider's secret-variable panel and retain it across every restart and deployment.
+Use this path when a provider installs npm packages and runs the package start script for you. Configure `npm start` as the start command and supply every required variable through the provider's environment or variables panel. Set `DATABASE_ENGINE` and a matching database URL reachable from that provider; omitting the engine keeps PostgreSQL. A local `.env` file is not required when the host supplies the variables. Generate `HELYX_DATA_ENCRYPTION_KEY` once with `node -e "console.log(require('node:crypto').randomBytes(32).toString('base64'))"`, store it in the provider's secret-variable panel and retain it across every restart and deployment.
 
 That key is also required when Giveaways is selected. Do not rotate it while a
 giveaway draw is in progress because it protects resumable selection
 checkpoints.
 
-If a provider cannot run `npm ci`, execute `npm start`, or connect to PostgreSQL, it cannot run this Helyx starter. A future hosting-specific download may package additional provider files, but it cannot remove the PostgreSQL requirement.
+If a provider cannot run `npm ci`, execute `npm start`, or connect to the selected database, it cannot run this Helyx starter.
+
+Run `npm run doctor` through the provider's console or one-off command facility
+with the same protected variables before enabling its start process. Run future
+installation and validation commands through the provider's supported process;
+do not assume a local `.env` file is required.
 
 ## Discord setup
 
@@ -58,38 +97,118 @@ If a provider cannot run `npm ci`, execute `npm start`, or connect to PostgreSQL
 2. Copy the application ID into `DISCORD_CLIENT_ID`. Generate a bot token and place it directly in `.env` or the host's variables panel; never place that token in Discord, Git, screenshots or support messages.
 3. Install the bot using both the `bot` and `applications.commands` scopes. Review the permissions required by your selected modules and grant only what you intend; administrator access is convenient but not required by Helyx core.
 
+Enable privileged intents only when selected features need them, in both the
+Discord Developer Portal and `.env`. For example, Counting needs
+`HELYX_MESSAGE_CONTENT_ENABLED=true`; Welcome and Access Control need
+`HELYX_GUILD_MEMBERS_ENABLED=true`; Levels needs both. Access Control's Password
+Entry also needs Message Content. Leaving these values false can prevent the
+corresponding features from being enabled or working.
+
 If Auto Moderation Enhanced mode is selected, also enable the privileged Message
 Content intent in the developer portal and set
 `HELYX_MESSAGE_CONTENT_ENABLED=true`. Enhanced scanning uses bounded worker
-threads inside this same bot and the same PostgreSQL database. Keep the default
+threads inside this same bot and the same selected database. Keep the default
 one worker until host CPU and memory measurements justify a value from two to
 four. No separate Ecko service, Redis instance, public endpoint or second
 database is required; unhealthy workers fall back to Discord-native Standard
 coverage.
 
-`npm start` validates the environment, connects to PostgreSQL, applies core and selected-module migrations safely, validates installed modules, synchronises Discord commands and then reports readiness. Do not run a separate migration command before every start. `npm run migrate` is available when you deliberately need to apply core migrations without starting Discord.
+`npm start` validates the environment, loads only the selected database adapter, applies core and selected-module migrations safely, validates installed modules, synchronises Discord commands and then reports readiness. Do not run a separate migration command before every start. `npm run migrate` is available when you deliberately need to apply core migrations without starting Discord.
+
+`npm run doctor` validates the environment, selected database connection, core
+migration history, selected packages and engine compatibility without signing
+in to Discord or modifying the database. Module migration inspection runs once
+core migrations have no pending entries. A fresh database can report pending
+migrations; normal startup applies them and probes required server capabilities.
+Doctor does not probe those capabilities or prove Discord readiness.
+
+Command registration is global or guild-scoped according to each reviewed command contribution. Discord may take time to refresh global commands. Installing a package does not enable its feature for a server; run `/helyx modules` in the server after startup to enable modules and configure their settings. Use `/permissions` when module or command access policies need to be changed.
+
+### Server-scoped module commands
+
+The template keeps guild command writes disabled and uses
+`HELYX_GLOBAL_COMMAND_MODE=legacy`. This does not disable all commands: core and
+compatible legacy commands can still register globally. However, server-scoped
+module command builds cannot be applied while guild writes are disabled.
+
+To use enabled-module command builds in servers you explicitly approve, set:
+
+```dotenv
+HELYX_GUILD_COMMAND_WRITES_ENABLED=true
+HELYX_GUILD_COMMAND_WRITE_SCOPE=allowlist
+HELYX_GUILD_COMMAND_WRITE_GUILD_IDS=12345678901234567
+HELYX_GLOBAL_COMMAND_MODE=platform-only
+```
+
+Replace the example with your Discord server ID, or a comma-separated list of
+approved server IDs, then restart the bot. These are server IDs, not application
+or channel IDs. An enabled allowlist must not be empty. `platform-only` keeps
+core/deployment commands global while feature commands are built for enabled
+modules in each server; removing legacy global commands can take time to appear
+in Discord. Module activation and command registration are still separate.
+Check the dashboard command-build status after enabling a module. Do not use
+the advanced `all` scope merely to bypass an allowlist error.
 
-`npm run doctor` validates the environment, PostgreSQL connection, existing migration history and selected packages without signing in to Discord or modifying the database. On a new database it reports migrations that `npm start` will apply automatically.
+### Cloud Connect
 
-Command registration is global or guild-scoped according to each reviewed command contribution. Discord may take time to refresh global commands. Installing a package does not enable its feature for a server; run `/helyx` in the server after startup to enable modules and configure their settings. Use `/permissions` when module or command access policies need to be changed.
+Generated self-host configuration enables the Cloud Connect connector by default, but it remains unpaired and shares nothing with the hosted dashboard until a deployment owner enters a one-use code with `/helyx cloud connect`. Set `HELYX_CLOUD_CONNECT_ENABLED=false` if this deployment will remain entirely local.
 
-Generated self-host configuration enables the Cloud Connect connector by default, but it remains unpaired and shares nothing with the hosted dashboard until a deployment owner enters a one-use code with `/helyx-cloud connect`. Set `HELYX_CLOUD_CONNECT_ENABLED=false` if this deployment will remain entirely local.
+Use the Discord application owner, an application team member, or an explicitly
+trusted user listed in `HELYX_OWNER_USER_IDS` to pair the deployment. Cloud
+Connect uses your bot's selected database and stable local encryption key; it
+does not require you to run a separate Helyx API, dashboard or PostgreSQL
+database alongside a MySQL bot. The hosted dashboard/control plane is managed
+separately by Helyx.
 
 ## Backups and upgrades
 
-- Back up PostgreSQL and the complete project directory before an upgrade.
-- Retain `package-lock.json`; use `npm ci` for repeatable installation.
-- Do not edit dependency versions or `helyx.modules.json` independently.
-- Run `npm run update:check` to compare the complete installed Helyx release set with the current reviewed catalogue.
-- Review the release notes, stop the bot, back up PostgreSQL, then run `npm run update`. Helyx backs up its managed project files, refreshes all exact Helyx versions and the lockfile together, and runs a clean install.
-- Run `npm run doctor` before restarting with `npm start`.
-- Existing starters that do not yet contain these scripts can use `npx --yes @helyx/cli@latest self-host update --check`, followed by the same command with `--confirm`, then `npm ci`.
-- Removing a package does not automatically delete retained module configuration or data.
-- Roll back application files and restore a compatible database backup if an upgrade cannot be completed safely.
+This release uses consolidated fresh-install migration baselines. Do not apply
+it as an ordinary upgrade to a database using an earlier migration chain.
+Retain the matching installed release and
+[contact Helyx support](https://docs.helyx.gg/contact/support/) before proceeding;
+no approved old-database transition is available yet. The updater does not
+convert, reset or back up a database.
+
+For a later release explicitly supporting an ordinary update from your installed
+state:
+
+1. Read its release notes and back up the selected database, project metadata,
+   `.env` and encryption key. Keep `package-lock.json`; do not edit individual
+   Helyx dependency versions or `helyx.modules.json`.
+2. Run `npm run update:check` to review the complete package-set change.
+3. Stop the bot. Compose users run `docker compose stop bot`, retaining the
+   database service and volume; managed hosts stop their application process.
+4. Run `npm run update`. Its script runs the metadata updater followed by
+   `npm ci`; the raw `helyx self-host update --confirm` command does not install
+   dependencies. Older starters can use
+   `npx --yes @helyx/cli@latest self-host update --check`, then the same command
+   with `--confirm`, followed by `npm ci`.
+5. Run doctor before restarting. Node.js users run `npm run doctor`, then
+   `npm start`. Docker users rebuild with `docker compose build bot`, run the
+   container doctor command above, then recreate with `docker compose up -d bot`.
+   Managed hosts use their installation, console and start facilities.
+6. Verify readiness and one representative workflow for each upgraded module.
+
+The updater backs up `.gitignore`, `package.json`, `package-lock.json`,
+`helyx.modules.json` and `SHA256SUMS` under `.helyx/backups/<timestamp>/`. It
+restores these files if metadata generation or lockfile validation fails inside
+`--confirm`. A later install, doctor or startup failure does not trigger that
+restore. This backup excludes `.env`, database data, `node_modules` and images.
+After a metadata restore, reinstall or rebuild the matching set and rerun doctor.
+If startup already changed the database, restoring project files does not undo
+its migrations; check the compatible backup/recovery plan before using old code.
+
+Removing a package does not automatically delete retained module data. Never
+alter migration history or checksums to make a mismatched release start.
 
 ## Adding or removing modules
 
-Use a newly generated manifest or the supported Helyx self-host command once module-change commands are released. A package being present does not enable it for a Discord server. Unknown packages, Git URLs, file paths and unreviewed registries are not supported.
+Choose the new selection in the Helyx builder and generate a starter in a new
+directory. The updater keeps the current selection and its required dependency
+closure; it is not an interactive add/remove command. For an existing database,
+review the module and release compatibility before changing the installation.
+A package being present does not enable it for a Discord server. Unknown
+packages, Git URLs, file paths and unreviewed registries are not supported.
 
 ## Support and security
 

package/templates/self-host/compose.mysql.yaml

@@ -0,0 +1,6 @@
+services:
+  bot:
+    build: .
+    restart: unless-stopped
+    env_file:
+      - .env