@helyx/bot 0.4.38 → 0.4.39

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.4.39
+
+### Patch Changes
+
+- 38c70f7: Ship maintained public documentation with the bot package and point newly generated self-host projects to its version-matched offline copy.
+
 ## 0.4.38
 
 ### Patch Changes

package/README.md

@@ -2,6 +2,11 @@
 
 The Helyx Discord runtime validates its environment, verifies and migrates PostgreSQL, validates explicitly configured module packages, applies their migrations, composes platform services, synchronises guild installations and commands, logs in with the non-privileged Guilds intent, and shuts down Discord, modules, and PostgreSQL safely.
 
+Version-matched public guides, operator runbooks, environment reference
+material, and module-authoring instructions ship at `documentation/README.md`
+inside this npm package. Repository-only `docs/` and `docs-old/` content is not
+published.
+
 Command contributions use an explicit registration policy: platform commands
 remain global, migrated customer commands are projected into enabled guilds,
 deployment commands stay with their deployment, and internal commands are

package/documentation/README.md

@@ -0,0 +1,32 @@
+# Helyx public documentation
+
+This is the portable, versioned documentation set for Helyx operators and
+module authors. It contains only material intended for public release and ships
+inside the matching `@helyx/bot` npm package.
+
+## Start here
+
+- [Install a self-hosted Helyx instance](guides/getting-started.md)
+- [Understand the self-hosting boundary](guides/self-hosting.md)
+- [Configure the environment](reference/environment.md)
+- [Operate installations and upgrades](runbooks/installation-and-upgrades.md)
+- [Plan backup and recovery](runbooks/backup-and-recovery.md)
+- [Build an independent module](modules/building-a-module.md)
+- [Test a module](modules/testing-a-module.md)
+- [Prepare a module package](modules/publishing-a-module.md)
+
+The complete working example is published separately as
+`@helyx/module-example`. It is intentionally independent: module-specific
+commands, settings, tests, and lifecycle behavior remain inside that module.
+
+## Publication boundary
+
+The repository's `docs/` and `docs-old/` trees are internal engineering and
+historical material. They are not part of the bot package. The hosted website
+is also a separate private build workspace. The release process copies only
+this `documentation/` tree into the bot tarball.
+
+Do not place credentials, private infrastructure addresses, incident evidence,
+unannounced plans, or internal deployment instructions here. Before a release,
+run `npm run documentation:check` and `npm run release:dry-run` from the Helyx
+repository root.

package/documentation/examples/.env.example

@@ -0,0 +1,117 @@
+# REQUIRED — EDIT THESE VALUES
+
+# Discord
+DISCORD_TOKEN=replace-me
+DISCORD_CLIENT_ID=12345678901234567
+# Explicit privileged gateway opt-in. Keep false unless a reviewed loaded module
+# requires message content and it is enabled in the Discord developer portal.
+HELYX_MESSAGE_CONTENT_ENABLED=false
+# Enable only when member inspection modules are loaded and the Discord Server
+# Members Intent is 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_URL=postgresql://database:5432/helyx
+DATABASE_SSL=disable
+
+# Included Docker database — both password values must match.
+PGUSER=helyx
+PGPASSWORD=replace-with-a-strong-password
+POSTGRES_DB=helyx
+POSTGRES_USER=helyx
+POSTGRES_PASSWORD=replace-with-a-strong-password
+
+# OPTIONAL EVERYDAY SETTINGS
+
+# Ready for dashboard linking, but remains unpaired until you use a one-use code.
+HELYX_CLOUD_CONNECT_ENABLED=true
+# Public dashboard origin used in bot-generated report links.
+# HELYX_DASHBOARD_PUBLIC_URL=https://app.helyx.gg
+# HELYX_OWNER_USER_IDS=12345678901234567
+
+# trace, debug, info, warn, error, fatal or silent
+LOG_LEVEL=info
+
+# Guild-scoped development commands only
+# DISCORD_INTERNAL_GUILD_ID=12345678901234567
+# APPROVED_ROLES=12345678901234567,12345678901234568
+
+# 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
+# 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
+# HELYX_SHARD_SCOPE=local
+# HELYX_SHARD_COUNT=2
+# HELYX_SHARD_WORKERS_PER_REPLICA=2
+# HELYX_SHARD_REDIS_URL=rediss://private-redis.example:6379
+# HELYX_SHARD_REDIS_NAMESPACE=helyx.self-host
+# HELYX_SHARD_GENERATION=local-20260728
+# HELYX_SHARD_DATABASE_CONNECTION_BUDGET=10
+# HELYX_SHARD_SUPERVISOR_DATABASE_POOL_MAX=2
+# HELYX_SHARD_WORKER_DATABASE_POOL_MAX=4
+# Redis URL and namespace are intentionally unsupported for the first
+# self-hosted release: do not uncomment them for local auto or fixed mode.
+
+# ADVANCED INTEGRATIONS — EDIT ONLY WHEN NEEDED
+
+# Additional reviewed module packages
+# HELYX_MODULE_PACKAGES=
+
+# Private dashboard control endpoint — configure both together
+# HELYX_BOT_CONTROL_SECRET=replace-with-a-base64-encoded-32-byte-key
+# HELYX_BOT_CONTROL_PORT=3001
+# HELYX_GUILD_RECONCILIATION_INTERVAL_SECONDS=900
+
+# Guild command writes remain off until explicitly enabled for known guild IDs.
+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
+
+# Hosted OAuth bridge. Keep disabled unless the API and bot share this secret.
+HELYX_OAUTH_ENABLED=false
+# HELYX_OAUTH_INTERNAL_SECRET=replace-with-a-base64-encoded-32-byte-key
+
+# DANGER ZONE — HELYX-MANAGED VALUES, DO NOT EDIT
+
+# Generated module selection
+HELYX_MODULE_CATALOGUE_PATH=./helyx.modules.json
+
+# Generated privately by npm run setup. Never change it while Cloud Connect is
+# enrolled or a checkpointed Giveaways draw is in progress.
+# HELYX_DATA_ENCRYPTION_KEY=replace-with-a-base64-encoded-32-byte-key
+
+# Official Cloud Connect endpoints
+# HELYX_CLOUD_API_URL=https://api.helyx.gg
+# HELYX_CLOUD_ENDPOINT=wss://connect.helyx.gg/v1/connect
+
+# Security audit retention
+# HELYX_CLOUD_AUDIT_RETENTION_DAYS=90
+# HELYX_CLOUD_CREDENTIAL_AUDIT_RETENTION_DAYS=365
+
+# Optional public status reporting. Keep disabled unless this installation has
+# its own approved Helyx status credentials.
+HELYX_STATUS_ENABLED=false
+# HELYX_STATUS_URL=https://status.helyx.gg
+# HELYX_STATUS_HEARTBEAT_SECRET=replace-with-a-base64-encoded-32-byte-key
+# HELYX_STATUS_HEARTBEAT_INTERVAL_SECONDS=60
+# CF_ACCESS_CLIENT_ID=replace-with-access-client-id
+# CF_ACCESS_CLIENT_SECRET=replace-with-access-client-secret
+
+# Runtime mode
+NODE_ENV=production

package/documentation/guides/getting-started.md

@@ -0,0 +1,51 @@
+# Getting started with self-hosted Helyx
+
+## Requirements
+
+- Node.js 24 or 26 and npm 11 or later.
+- A Discord application and bot token.
+- PostgreSQL with a database you can back up and restore.
+- Permission to install the bot in the Discord servers you manage.
+
+Keep the bot token, database credentials, encryption keys, and control secrets
+outside source control.
+
+## Create the project
+
+Install the Helyx CLI, then generate a reviewed starter project using the
+release manifest supplied by Helyx:
+
+```sh
+npm install --global @helyx/cli
+helyx self-host init --manifest ./helyx-build.json --output ./helyx --install
+cd helyx
+helyx setup
+```
+
+`helyx setup` creates `.env` from `.env.example` only when `.env` does not
+already exist. Edit the required Discord and database values before continuing.
+See the [environment reference](../reference/environment.md).
+
+## Validate before login
+
+```sh
+npm run doctor
+```
+
+The doctor checks configuration, PostgreSQL connectivity, migration history,
+and installed module metadata without logging in to Discord or changing the
+database. Correct every reported error before starting.
+
+## Start Helyx
+
+```sh
+npm start
+```
+
+For a long-running host, use the service or container supervision provided by
+your operating system or hosting platform. Configure automatic restarts with a
+bounded delay, retain logs without secrets, and arrange database backups before
+inviting production traffic.
+
+Next read the [self-hosting guide](self-hosting.md) and the
+[installation and upgrade runbook](../runbooks/installation-and-upgrades.md).

package/documentation/guides/self-hosting.md

@@ -0,0 +1,40 @@
+# Self-hosting responsibilities
+
+Self-hosting gives you control of the Helyx runtime and its data. It also makes
+you responsible for the host, PostgreSQL, Discord credentials, environment
+configuration, updates, monitoring, backups, and recovery testing.
+
+## Supported shape
+
+A normal installation contains one generated Helyx project, one PostgreSQL
+database, the reviewed core packages, and independently selected modules. Keep
+module boundaries intact: a module must be installable, configurable, testable,
+and removable without relying on unrelated module behavior.
+
+Helyx supports Docker Compose and direct Node.js operation. The generated
+project is the source of truth for its pinned public packages and module
+catalogue. Do not copy source trees from the Helyx repository into an
+installation.
+
+## Secrets and access
+
+- Store `.env` outside version control and restrict who can read it.
+- Use a dedicated database user and the least privileges supported by your
+  deployment.
+- Rotate a Discord token or control secret if it may have been exposed.
+- Do not paste secret values into logs, issues, screenshots, or support chats.
+- Limit network access to PostgreSQL and private control endpoints.
+
+## Operating baseline
+
+- Run `npm run doctor` after configuration or package changes.
+- Watch process health, database capacity, command deployment errors, and module
+  health.
+- Back up both PostgreSQL and the environment or key material needed to decrypt
+  its records.
+- Test recovery in a disposable environment.
+- Apply compatible releases as one reviewed set; do not upgrade internal Helyx
+  packages independently.
+
+Cloud Connect is optional. Enabling it does not transfer responsibility for the
+self-hosted process, database, secrets, or backups to Helyx.

package/documentation/modules/building-a-module.md

@@ -0,0 +1,37 @@
+# Building an independent Helyx module
+
+Start from the published `@helyx/module-example` package. It contains a
+self-contained TypeScript project, manifest, source, tests, and packaging
+allowlist that can be copied into a new repository or workspace.
+
+## Required parts
+
+Every module needs:
+
+- a unique npm package name and semantic version;
+- a Helyx module manifest parsed by `@helyx/module-manifest`;
+- a default JavaScript export created with `defineModule` from `@helyx/sdk`;
+- explicit `start` and `stop` lifecycle functions;
+- a privacy declaration and provider, including when no personal data is held;
+- compiled JavaScript and declarations matching the package exports;
+- tests for manifest parity, loading, lifecycle behavior, and each declared
+  contribution.
+
+Dashboard fields need matching configuration validation. Manifest command IDs
+must exactly match executable command contributions. Declare Discord
+permissions and privileged capabilities only when the module actually needs
+them.
+
+## Preserve modularity
+
+A module owns its commands, configuration, data, migrations, health, and tests.
+Do not merge unrelated features into one module merely to share code. Put
+reusable contracts in a support package when necessary, and keep each module
+independently installable and usable.
+
+Do not import private Helyx applications, another module's source files, or
+repository-relative configuration. Depend only on published packages with
+compatible version ranges. Module behavior must fail clearly when an optional
+external service is unavailable.
+
+See [testing a module](testing-a-module.md) before adding product behavior.

package/documentation/modules/publishing-a-module.md

@@ -0,0 +1,27 @@
+# Preparing a module for npm
+
+This checklist prepares a package for review. It does not authorize publishing
+to npm or adding a module to the official Helyx catalogue.
+
+1. Choose a unique package name and keep the package version equal to the
+   manifest version.
+2. Use compatible ranges for `@helyx/module-manifest` and `@helyx/sdk`.
+3. Compile to `dist/` and expose both a JavaScript default entry and a `.d.ts`
+   declaration entry.
+4. Use an explicit `files` allowlist. Exclude source maps and TypeScript build
+   caches.
+5. Include `manifest.json`, `README.md`, `CHANGELOG.md`, and the licence that
+   applies to your code.
+6. Run the complete test suite and `npm pack --dry-run` from a clean checkout.
+7. Extract the generated tarball into a temporary project and import its default
+   export under a supported Node.js version.
+8. Search the packed file list for `.env`, credentials, private URLs, logs,
+   dumps, tests with fixtures containing real data, and repository-only notes.
+
+Third-party modules choose and clearly state their own licence. Do not copy the
+Helyx Source Available Licence notice into a third-party module unless that
+licence actually governs the module.
+
+Publishing a package does not make it an official or reviewed Helyx module.
+Catalogue inclusion, security review, permissions, privacy declarations, and
+release support are separate decisions.

package/documentation/modules/testing-a-module.md

@@ -0,0 +1,46 @@
+# Testing a Helyx module
+
+The `@helyx/module-example` suite demonstrates four compatibility layers.
+
+## Manifest and export
+
+Parse `manifest.json`, import the module's default export, and assert that the
+runtime manifest equals the packaged manifest. This prevents metadata from
+drifting away from executable contributions.
+
+## Lifecycle
+
+Call `start`, `health`, and `stop` with a minimal SDK runtime context. Verify
+observable behavior and make both lifecycle functions safe for the runtime to
+call. Do not start network listeners or timers at import time.
+
+## Dashboard
+
+Parse the complete manifest with `@helyx/module-manifest`. Test valid defaults,
+boundary values, wrong types, and missing required settings against the
+module's configuration contribution. Each dashboard setting key must have one
+matching validator field.
+
+## Slash commands
+
+Assert that manifest command IDs and executable command names are identical.
+Build the command with the same Discord.js builders used by Helyx, inspect the
+generated application-command payload, and execute the handler with a fake SDK
+context. Test acknowledgement, context, integration type, option limits, and a
+representative response without contacting Discord.
+
+## Before packaging
+
+Run the module's build and test scripts, then inspect exactly what npm would
+include:
+
+```sh
+npm run build
+npm test
+npm pack --dry-run
+```
+
+The tarball needs compiled exports, declarations, the manifest, instructions,
+licence, and any source or tests deliberately offered as a template. It must
+not contain credentials, logs, source maps, build caches, or internal Helyx
+documentation.

package/documentation/reference/environment.md

@@ -0,0 +1,42 @@
+# Environment reference
+
+Start from [the published example](../examples/.env.example). The example is a
+copy of the starter emitted by the supported CLI and is checked for drift.
+
+## Required values
+
+`DISCORD_TOKEN` is the bot token from the Discord developer portal.
+`DISCORD_CLIENT_ID` is the application's numeric ID. `DATABASE_URL` points to
+PostgreSQL; `DATABASE_SSL` must match the database provider. Docker users must
+also replace the example PostgreSQL password consistently in `PGPASSWORD` and
+`POSTGRES_PASSWORD`.
+
+## Safe defaults
+
+Privileged Discord intents, privacy execution, hosted OAuth, status reporting,
+guild command writes, and advanced sharding stay disabled until their complete
+requirements are deliberately configured. An empty variable still counts as a
+configured value in many environments, so leave unused optional lines
+commented.
+
+`HELYX_CLOUD_CONNECT_ENABLED=true` makes an installation ready to be paired; it
+does not pair the installation by itself. Keep official endpoint overrides
+commented unless Helyx support directs otherwise.
+
+## Generated values
+
+The CLI owns `HELYX_MODULE_CATALOGUE_PATH` and may generate
+`HELYX_DATA_ENCRYPTION_KEY`. Preserve generated key material for the lifetime of
+the encrypted data. Losing it can make records unrecoverable; replacing it is
+not a password reset.
+
+## Verification
+
+After every environment change, run:
+
+```sh
+npm run doctor
+```
+
+Never include the real `.env` file in an npm package, container image layer,
+source archive, or support bundle.

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

@@ -0,0 +1,41 @@
+# Backup and recovery runbook
+
+A usable Helyx backup includes PostgreSQL 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.
+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.
+5. Apply a documented retention schedule to both active and backup data.
+
+Never commit a database dump or real environment file to Git and never place it
+inside an npm package.
+
+## Test recovery
+
+At a regular interval:
+
+1. Create a disposable network and a separate empty database.
+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.
+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.
+
+## Incident recovery
+
+Stop writes before a destructive restore. Preserve evidence needed to
+understand the incident, select a known-good backup, restore into a new database
+when possible, validate it, then deliberately switch the runtime. Do not test a
+restore over the only production database.

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

@@ -0,0 +1,48 @@
+# Installation and upgrade runbook
+
+## 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.
+
+## 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
+   metadata and environment file.
+3. Stop the Helyx process cleanly.
+4. Preview the compatible release set:
+
+   ```sh
+   helyx self-host update --check
+   ```
+
+5. Apply it only after reviewing the complete change:
+
+   ```sh
+   helyx self-host update --confirm
+   npm ci
+   npm run doctor
+   ```
+
+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.
+
+## Failed validation
+
+Leave the process stopped, retain sanitized 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@helyx/bot",
-  "version": "0.4.38",
+  "version": "0.4.39",
   "description": "Production Discord runtime for the modular Helyx platform.",
   "keywords": [
     "helyx",
@@ -32,6 +32,7 @@
     "dist",
     "!dist/*.tsbuildinfo",
     "!dist/**/*.map",
+    "documentation",
     "CHANGELOG.md",
     "README.md",
     "LICENSE"
@@ -44,6 +45,7 @@
   },
   "scripts": {
     "build": "tsc -b",
+    "prepack": "node ../../scripts/public-documentation.mjs --sync-bot",
     "dev": "node --env-file-if-exists=../../.env --import tsx src/index.ts",
     "start": "node --env-file-if-exists=../../.env dist/index.js"
   },