@helyx/cli 1.2.2 → 1.4.0

package/dist/self-host/project-generator.js

@@ -4,6 +4,7 @@ import { mkdir, readFile, readdir, rm, stat, writeFile, } from "node:fs/promises
 import { dirname, parse, resolve } from "node:path";
 import { isSelfHostModuleCustomerSelectable, } from "./catalogue.js";
 import { parseSelfHostBuildManifest, } from "./manifest.js";
+import { databaseAdaptersForCatalogue, } from "./database-adapters.js";
 const generatedFileNames = [
     ".env.example",
     ".gitignore",
@@ -16,6 +17,7 @@ const generatedFileNames = [
 export async function generateSelfHostProject(options) {
     const manifest = parseSelfHostBuildManifest(options.manifest, options.catalogue);
     const targetDirectory = resolve(options.targetDirectory);
+    const databaseAdapters = options.databaseAdapters ?? databaseAdaptersForCatalogue(options.catalogue);
     const signal = options.signal ?? AbortSignal.timeout(120_000);
     signal.throwIfAborted();
     assertSafeTargetDirectory(targetDirectory);
@@ -24,7 +26,7 @@ export async function generateSelfHostProject(options) {
     try {
         await mkdir(targetDirectory);
         created = true;
-        await writeGeneratedFiles(targetDirectory, manifest, options.catalogue);
+        await writeGeneratedFiles(targetDirectory, manifest, options.catalogue, databaseAdapters);
         signal.throwIfAborted();
         const runner = options.commandRunner ?? runNpmCommand;
         await runner([
@@ -35,7 +37,7 @@ export async function generateSelfHostProject(options) {
             "--no-fund",
         ], targetDirectory, signal);
         signal.throwIfAborted();
-        await validateGeneratedLockfile(targetDirectory, manifest);
+        await validateGeneratedLockfile(targetDirectory, manifest, databaseAdapters);
         signal.throwIfAborted();
         if (options.install) {
             await runner(["ci", "--no-audit", "--no-fund"], targetDirectory, signal);
@@ -56,10 +58,14 @@ export async function generateSelfHostProject(options) {
         throw error;
     }
 }
-async function writeGeneratedFiles(targetDirectory, manifest, catalogue) {
+async function writeGeneratedFiles(targetDirectory, manifest, catalogue, databaseAdapters) {
+    const databaseEngine = "databaseEngine" in manifest
+        ? (manifest.databaseEngine ?? "postgresql")
+        : "postgresql";
     const dependencyEntries = [
         [manifest.core.package, manifest.core.version],
         [manifest.generator.package, manifest.generator.version],
+        ...databaseAdapters.map((adapter) => [adapter.package, adapter.version]),
         ...manifest.modules.map((module) => [module.package, module.version]),
     ];
     dependencyEntries.sort(([left], [right]) => left.localeCompare(right, "en"));
@@ -85,20 +91,36 @@ async function writeGeneratedFiles(targetDirectory, manifest, catalogue) {
     const moduleCatalogue = {
         schemaVersion: 1,
         packages: manifest.modules.map((module) => module.package),
+        ...(databaseEngine === "mysql" ? { databaseEngine } : {}),
     };
     await writeFile(resolve(targetDirectory, "package.json"), formatJson(packageJson), "utf8");
     await writeFile(resolve(targetDirectory, "helyx.modules.json"), formatJson(moduleCatalogue), "utf8");
     for (const fileName of generatedFileNames) {
-        const template = await readFile(templateUrl(fileName), "utf8");
+        const template = await readFile(fileName === "compose.yaml" && databaseEngine === "mysql"
+            ? mysqlComposeTemplateUrl()
+            : templateUrl(fileName), "utf8");
+        const rendered = fileName === ".env.example"
+            ? renderEnvironmentExample(template, databaseEngine)
+            : fileName === "README.md"
+                ? renderReadme(template, manifest, catalogue, databaseEngine)
+                : template;
         if (fileName === ".env.example")
-            validateEnvironmentTemplate(template);
-        const content = fileName === "README.md"
-            ? renderReadme(template, manifest, catalogue)
-            : normalizeCrLf(template);
+            validateEnvironmentTemplate(rendered, databaseEngine);
+        const content = normalizeCrLf(rendered);
         await writeFile(resolve(targetDirectory, fileName), content, "utf8");
     }
 }
-function renderReadme(template, manifest, catalogue) {
+function renderEnvironmentExample(template, databaseEngine) {
+    if (databaseEngine === "postgresql")
+        return template;
+    return template
+        .replaceAll("\r\n", "\n")
+        .replace("# Docker: keep the URL. Direct Node.js/managed hosting: use your provider URL.\nDATABASE_ENGINE=postgresql\nDATABASE_URL=postgresql://database:5432/helyx", "# Use the MySQL-compatible database URL supplied by your provider.\n# The included Compose file runs only the bot; it never starts a second database.\nDATABASE_ENGINE=mysql\nDATABASE_URL=mysql://user:password@host:3306/helyx")
+        .replace(/# Included Docker database[^\n]*\nPGUSER=helyx\nPGPASSWORD=replace-with-a-strong-password\nPOSTGRES_DB=helyx\nPOSTGRES_USER=helyx\nPOSTGRES_PASSWORD=replace-with-a-strong-password\n\n/u, "")
+        .replace("HELYX_SHARD_MODE=off\n", "# MySQL-compatible self-hosting currently supports only this unsharded mode.\nHELYX_SHARD_MODE=off\n")
+        .replace("DATABASE_SSL=disable", "DATABASE_SSL=require");
+}
+function renderReadme(template, manifest, catalogue, databaseEngine) {
     const modulesById = new Map(catalogue.modules.map((module) => [module.id, module]));
     const selected = manifest.modules.length
         ? manifest.modules
@@ -111,7 +133,19 @@ function renderReadme(template, manifest, catalogue) {
             .filter((line) => line !== null)
             .join("\n")
         : "- No feature modules selected. This is a core-only installation.";
-    return normalizeCrLf(template.replace("{{SELECTED_MODULES}}", selected));
+    let rendered = template
+        .replaceAll("\r\n", "\n")
+        .replace("{{SELECTED_MODULES}}", selected);
+    if (databaseEngine === "mysql") {
+        rendered = rendered
+            .replace("3. Edit `.env`, replace every placeholder, set `DATABASE_ENGINE` to `postgresql` or `mysql`, and set the matching `DATABASE_URL`. Omitting `DATABASE_ENGINE` selects PostgreSQL.", "3. Edit `.env`, replace every placeholder, keep `DATABASE_ENGINE=mysql` and `HELYX_SHARD_MODE=off`, and set `DATABASE_URL` to the MySQL-compatible URL supplied by your provider. Percent-encode special characters in URL credentials.")
+            .replace("Use this path when Docker with Compose support is available. The included configuration runs both Helyx and PostgreSQL 17.", "Use this path when Docker with Compose support is available. The included configuration runs only Helyx; it connects to your existing MySQL-compatible database and does not create a second database service.")
+            .replace("2. Edit `.env` and replace all placeholder credentials and passwords.\n3. Keep `DATABASE_ENGINE=postgresql` with the supplied internal `DATABASE_URL` and `DATABASE_SSL=disable`.\n4. Run `docker compose up --build -d`.\n5. Review startup with `docker compose logs -f bot`.\n6. Stop services with `docker compose down`. Do not add `--volumes` unless you deliberately intend to delete the database volume.", "2. Edit `.env` and replace all placeholder credentials. Keep `DATABASE_ENGINE=mysql` and supply your provider's reachable `DATABASE_URL` and required `DATABASE_SSL` setting.\n3. Run `docker compose up --build -d`.\n4. Review startup with `docker compose logs -f bot`.\n5. Stop the bot with `docker compose down`. Your external database is not managed by this Compose file.");
+    }
+    return rendered;
+}
+function mysqlComposeTemplateUrl() {
+    return new URL("../../templates/self-host/compose.mysql.yaml", import.meta.url);
 }
 function templateUrl(fileName) {
     const templateName = fileName === ".npmrc"
@@ -130,19 +164,26 @@ function normalizeCrLf(value) {
         .replaceAll("\r", "\n")
         .replaceAll("\n", "\r\n");
 }
-function validateEnvironmentTemplate(template) {
+function validateEnvironmentTemplate(template, databaseEngine) {
     const lines = new Set(template
         .replaceAll("\r\n", "\n")
         .split("\n")
         .map((line) => line.trim()));
     for (const [key, definition] of Object.entries(selfHostEnvironmentContract)) {
-        const expected = `${definition.optional ? "# " : ""}${key}=${definition.value}`;
+        const value = key === "DATABASE_ENGINE"
+            ? databaseEngine
+            : key === "DATABASE_URL" && databaseEngine === "mysql"
+                ? "mysql://user:password@host:3306/helyx"
+                : key === "DATABASE_SSL" && databaseEngine === "mysql"
+                    ? "require"
+                    : definition.value;
+        const expected = `${definition.optional ? "# " : ""}${key}=${value}`;
         if (!lines.has(expected)) {
             throw new Error(`Self-host environment template does not match the bot contract: ${key}`);
         }
     }
 }
-async function validateGeneratedLockfile(targetDirectory, manifest) {
+async function validateGeneratedLockfile(targetDirectory, manifest, databaseAdapters) {
     const lockfilePath = resolve(targetDirectory, "package-lock.json");
     const lockfile = JSON.parse(await readFile(lockfilePath, "utf8"));
     if (!isRecord(lockfile) || !isRecord(lockfile.packages)) {
@@ -159,6 +200,7 @@ async function validateGeneratedLockfile(targetDirectory, manifest) {
     const expected = new Map([
         [manifest.core.package, manifest.core.version],
         [manifest.generator.package, manifest.generator.version],
+        ...databaseAdapters.map((adapter) => [adapter.package, adapter.version]),
         ...manifest.modules.map((module) => [module.package, module.version]),
     ]);
     if (Object.keys(lockedDependencies).length !== expected.size ||
@@ -265,14 +307,17 @@ function isRecord(value) {
 // This compile-time map intentionally stays adjacent to the generator. Adding a
 // bot environment field makes the generated contract fail to compile until the
 // self-host example receives an explicit safe value or omission decision.
-// Support service authentication, staff delivery, and Verification remain
-// hosted-only and are deliberately excluded from generated self-host projects.
+// Request My Data, support service authentication, staff delivery, and
+// Verification remain hosted-only and are deliberately excluded from generated
+// self-host projects.
 export const selfHostEnvironmentContract = {
+    DATABASE_ENGINE: { value: "postgresql", optional: false },
     DATABASE_URL: {
         value: "postgresql://database:5432/helyx",
         optional: false,
     },
     DATABASE_SSL: { value: "disable", optional: false },
+    HELYX_DATABASE_STARTUP_MODE: { value: "apply", optional: true },
     HELYX_RUNTIME_PROFILE: { value: "self-hosted", optional: false },
     HELYX_DEPLOYMENT_ENVIRONMENT: { value: "self-hosted", optional: false },
     DISCORD_TOKEN: { value: "replace-me", optional: false },
@@ -324,16 +369,7 @@ export const selfHostEnvironmentContract = {
     HELYX_GUILD_COMMAND_RELEASE_ID: { value: "", optional: true },
     HELYX_GLOBAL_COMMAND_MODE: { value: "legacy", optional: false },
     HELYX_GUILD_COMMAND_WRITE_GUILD_IDS: { value: "", optional: true },
-    HELYX_PRIVACY_ENABLED: { value: "false", optional: false },
     HELYX_GUILD_MEMBERS_ENABLED: { value: "false", optional: false },
-    HELYX_PRIVACY_EXECUTOR_DATABASE_URL: {
-        value: "<dedicated-privacy-executor-postgresql-url>",
-        optional: true,
-    },
-    HELYX_PRIVACY_EXECUTOR_DATABASE_SSL: {
-        value: "disable",
-        optional: true,
-    },
     HELYX_CLOUD_CONNECT_ENABLED: { value: "true", optional: false },
     HELYX_CLOUD_ENROLMENT_TOKEN: {
         value: "replace-with-a-short-lived-enrolment-code",

package/dist/self-host/update.d.ts

@@ -2,14 +2,15 @@ import { type SelfHostCatalogue } from "./catalogue.js";
 export declare const DEFAULT_SELF_HOST_CATALOGUE_URL = "https://api.helyx.gg/self-host/catalogue";
 export interface SelfHostUpdateChange {
     package: string;
-    currentVersion: string;
-    targetVersion: string;
-    direction: "upgrade" | "downgrade";
+    currentVersion: string | null;
+    targetVersion: string | null;
+    direction: "add" | "upgrade" | "downgrade" | "remove";
 }
 export interface SelfHostUpdatePlan {
     projectDirectory: string;
     catalogueVersion: number;
     changes: SelfHostUpdateChange[];
+    moduleSelectionChanged: boolean;
     upToDate: boolean;
 }
 export type SelfHostUpdateCommandRunner = (arguments_: readonly string[], workingDirectory: string) => Promise<void>;

package/dist/self-host/update.js

@@ -4,7 +4,9 @@ import { spawn } from "node:child_process";
 import { copyFile, mkdir, readFile, readdir, rename, stat, writeFile, } from "node:fs/promises";
 import { parse, resolve } from "node:path";
 import { z } from "zod";
-import { parseSelfHostCatalogue } from "./catalogue.js";
+import { isSelfHostModuleCustomerSelectable, parseSelfHostCatalogue, selfHostDatabaseEngineSchema, } from "./catalogue.js";
+import { databaseAdaptersForCatalogue } from "./database-adapters.js";
+import { createSelfHostBuildManifest } from "./manifest.js";
 export const DEFAULT_SELF_HOST_CATALOGUE_URL = "https://api.helyx.gg/self-host/catalogue";
 const maximumCatalogueBytes = 512 * 1_024;
 const catalogueTimeoutMilliseconds = 15_000;
@@ -24,7 +26,8 @@ const packageJsonSchema = z
 const moduleSelectionSchema = z
     .object({
     schemaVersion: z.literal(1),
-    packages: z.array(modulePackage).max(30),
+    packages: z.array(modulePackage),
+    databaseEngine: selfHostDatabaseEngineSchema.optional(),
 })
     .strict()
     .superRefine((value, context) => {
@@ -53,14 +56,16 @@ export async function updateSelfHostProject(options = {}) {
             ? Promise.resolve(options.catalogue)
             : (options.catalogueLoader ?? loadCurrentSelfHostCatalogue)(),
     ]);
-    const targetDependencies = targetHelyxDependencies(catalogue, selection);
-    validateManagedDependencies(packageJson.dependencies, targetDependencies);
-    const changes = collectChanges(packageJson.dependencies, targetDependencies);
+    const target = targetHelyxDependencies(catalogue, selection);
+    validateManagedDependencies(packageJson.dependencies, target.dependencies, selection.packages, target.addedDependencyPackages);
+    const changes = collectChanges(packageJson.dependencies, target.dependencies);
+    const selectionChanged = JSON.stringify(selection.packages) !== JSON.stringify(target.packages);
     const plan = {
         projectDirectory,
         catalogueVersion: catalogue.catalogueVersion,
         changes,
-        upToDate: changes.length === 0,
+        moduleSelectionChanged: selectionChanged,
+        upToDate: changes.length === 0 && !selectionChanged,
     };
     if (!options.apply || plan.upToDate)
         return plan;
@@ -75,11 +80,16 @@ export async function updateSelfHostProject(options = {}) {
                 update: "helyx self-host update --confirm && npm ci",
             },
             dependencies: {
-                ...packageJson.dependencies,
-                ...Object.fromEntries(targetDependencies),
+                ...Object.fromEntries(Object.entries(packageJson.dependencies).filter(([name]) => !name.startsWith("@helyx/"))),
+                ...Object.fromEntries(target.dependencies),
             },
         };
         await atomicWriteJson(resolve(projectDirectory, "package.json"), nextPackageJson);
+        if (selectionChanged)
+            await atomicWriteJson(resolve(projectDirectory, "helyx.modules.json"), {
+                ...selection,
+                packages: target.packages,
+            });
         const runner = options.commandRunner ?? runNpmCommand;
         await runner([
             "install",
@@ -88,7 +98,7 @@ export async function updateSelfHostProject(options = {}) {
             "--no-audit",
             "--no-fund",
         ], projectDirectory);
-        await validateUpdatedLockfile(projectDirectory, targetDependencies);
+        await validateUpdatedLockfile(projectDirectory, target.dependencies);
         await writeChecksums(projectDirectory);
         return plan;
     }
@@ -185,41 +195,74 @@ function targetHelyxDependencies(catalogue, selection) {
             module.version === null) {
             throw new Error(`Selected module is not in the current reviewed free live release: ${selectedPackage}`);
         }
-        return [module.package, module.version];
+        return module;
     });
-    return new Map([
+    if (selection.databaseEngine === "mysql" && catalogue.schemaVersion !== 2) {
+        throw new Error("The reviewed self-host catalogue lacks MySQL compatibility metadata");
+    }
+    const modules = catalogue.schemaVersion === 2
+        ? createSelfHostBuildManifest(catalogue, selected
+            .filter(isSelfHostModuleCustomerSelectable)
+            .map(({ id }) => id), selection.databaseEngine ?? "postgresql").modules
+        : selected;
+    const dependencies = new Map([
         [catalogue.core.package, catalogue.core.version],
         [catalogue.generator.package, catalogue.generator.version],
-        ...selected,
+        ...databaseAdaptersForCatalogue(catalogue).map((adapter) => [adapter.package, adapter.version]),
+        ...modules.map((module) => [module.package, module.version]),
     ]);
+    return {
+        dependencies,
+        packages: modules.map(({ package: name }) => name),
+        addedDependencyPackages: modules
+            .filter((module) => "moduleKind" in module &&
+            module.moduleKind === "internal_dependency" &&
+            !selection.packages.includes(module.package))
+            .map(({ package: name }) => name),
+    };
 }
-function validateManagedDependencies(current, target) {
+function validateManagedDependencies(current, target, selectedPackages, addedDependencyPackages) {
     for (const [name, version] of Object.entries(current)) {
         if (!name.startsWith("@helyx/"))
             continue;
         packageName.parse(name);
         exactVersion.parse(version);
-        if (!target.has(name)) {
+        if (!target.has(name) && !selectedPackages.includes(name)) {
             throw new Error(`Unexpected Helyx dependency is not controlled by helyx.modules.json: ${name}`);
         }
     }
     for (const name of target.keys()) {
-        if (!(name in current)) {
+        if (!(name in current) &&
+            !addedDependencyPackages.includes(name) &&
+            name !== "@helyx/database" &&
+            name !== "@helyx/database-mysql") {
             throw new Error(`Generated project is missing Helyx dependency: ${name}`);
         }
     }
 }
 function collectChanges(current, target) {
-    return [...target]
-        .filter(([name, version]) => current[name] !== version)
-        .map(([name, version]) => ({
-        package: name,
-        currentVersion: current[name],
-        targetVersion: version,
-        direction: semver.gt(version, current[name])
-            ? "upgrade"
-            : "downgrade",
-    }))
+    const names = new Set([
+        ...target.keys(),
+        ...Object.keys(current).filter((name) => name.startsWith("@helyx/")),
+    ]);
+    return [...names]
+        .filter((name) => current[name] !== target.get(name))
+        .map((name) => {
+        const version = target.get(name) ?? null;
+        const currentVersion = current[name] ?? null;
+        return {
+            package: name,
+            currentVersion,
+            targetVersion: version,
+            direction: version === null
+                ? "remove"
+                : currentVersion === null
+                    ? "add"
+                    : semver.gt(version, currentVersion)
+                        ? "upgrade"
+                        : "downgrade",
+        };
+    })
         .sort((left, right) => left.package.localeCompare(right.package, "en"));
 }
 async function readProjectJson(projectDirectory) {
@@ -277,6 +320,10 @@ async function validateUpdatedLockfile(projectDirectory, target) {
             throw new Error(`Updated package-lock.json does not pin ${name}@${version}`);
         }
     }
+    for (const name of Object.keys(root.dependencies)) {
+        if (name.startsWith("@helyx/") && !target.has(name))
+            throw new Error(`Updated package-lock.json retains ${name}`);
+    }
 }
 async function writeChecksums(projectDirectory) {
     const fileNames = (await readdir(projectDirectory))

package/dist/setup.d.ts

@@ -7,6 +7,7 @@ export interface SetupSelfHostEnvironmentResult {
     created: boolean;
     dataEncryptionKeyCreated: boolean;
     dockerComposeAvailable: boolean;
+    databaseEngine: "postgresql" | "mysql";
     environmentPath: string;
 }
 export declare function setupSelfHostEnvironment(options?: SetupSelfHostEnvironmentOptions): Promise<SetupSelfHostEnvironmentResult>;

package/dist/setup.js

@@ -12,6 +12,11 @@ export async function setupSelfHostEnvironment(options = {}) {
     await assertGeneratedStarter(cwd);
     const examplePath = resolve(cwd, ".env.example");
     const environmentPath = resolve(cwd, ".env");
+    const example = parseEnv(await readFile(examplePath, "utf8"));
+    const databaseEngine = example.DATABASE_ENGINE ?? "postgresql";
+    if (databaseEngine !== "postgresql" && databaseEngine !== "mysql") {
+        throw new Error("The starter has an unsupported DATABASE_ENGINE value");
+    }
     let created = false;
     try {
         await copyFile(examplePath, environmentPath, constants.COPYFILE_EXCL);
@@ -27,6 +32,7 @@ export async function setupSelfHostEnvironment(options = {}) {
         created,
         dataEncryptionKeyCreated,
         dockerComposeAvailable: await (options.detectDockerCompose ?? detectDockerCompose)(),
+        databaseEngine,
         environmentPath,
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@helyx/cli",
-  "version": "1.2.2",
+  "version": "1.4.0",
   "description": "Command-line tools for running and generating self-hosted Helyx deployments.",
   "keywords": [
     "helyx",
@@ -25,7 +25,7 @@
   },
   "publishConfig": {
     "access": "public",
-    "provenance": true
+    "provenance": false
   },
   "type": "module",
   "files": [
@@ -52,12 +52,15 @@
     "build": "tsc -b"
   },
   "dependencies": {
-    "@helyx/bot": ">=1.0.0 <2.0.0",
-    "@helyx/config": ">=1.0.0 <2.0.0",
-    "@helyx/database": ">=2.0.0 <3.0.0",
+    "@helyx/bot": ">=1.4.0 <2.0.0",
+    "@helyx/config": ">=1.4.0 <2.0.0",
+    "@helyx/database": ">=2.4.0 <3.0.0",
     "semver": "7.8.5",
     "zod": "4.4.3"
   },
+  "optionalDependencies": {
+    "@helyx/database-mysql": ">=0.2.0 <0.3.0"
+  },
   "devDependencies": {
     "@types/semver": "7.7.1"
   }