@helyx/cli 1.5.0 → 1.6.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 1.6.0
+
+### Minor Changes
+
+- b698422: Add the optional `helyx envbuilder` command and generated starter npm script.
+  Preserve platform builder selections in build manifests and include standalone
+  batch, PowerShell or POSIX scripts only when selected. The guided builder runs
+  locally, checks input format, masks saved credentials and preserves encryption
+  keys and custom settings until the operator confirms saving.
+
 ## 1.5.0
 
 ### Minor Changes

package/README.md

@@ -20,6 +20,12 @@ operation supports a local or hosted PostgreSQL or MySQL-compatible database.
 and performs the bot bootstrap, including core and installed-module migrations.
 `migrate` applies only core migrations and exits.
 
+Generated starters also include the optional `npm run envbuilder` command.
+After `npm ci`, it runs `helyx envbuilder`, a local guided `.env` builder with
+no connection tests. Additional standalone Windows batch, PowerShell and
+macOS/Linux scripts are included only when selected for the download. Setup
+and startup remain independent.
+
 `doctor` checks the complete bot environment, connectivity, immutable core
 migration history, package metadata and selected module/engine compatibility
 without logging in to Discord or changing the database. It inspects module

package/dist/cli.js

@@ -24,6 +24,10 @@ try {
     else if (command === "setup") {
         await setup();
     }
+    else if (command === "envbuilder") {
+        const builder = (await import(new URL("../templates/self-host/env-builder.mjs", import.meta.url).href));
+        await builder.runEnvironmentBuilder(process.argv[3]);
+    }
     else if (command === "self-host") {
         await runSelfHostCommand(process.argv.slice(3));
     }
@@ -141,6 +145,7 @@ function printHelp() {
 
 Commands:
   setup    Create .env safely and explain the available hosting paths
+  envbuilder  Optionally create or update .env with a local guided builder
   start    Start the Helyx Discord bot
   migrate  Apply core migrations for the selected database engine and exit
   doctor   Validate environment, database schema and module packages

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 export * from "./self-host/catalogue.js";
 export * from "./self-host/command.js";
 export * from "./self-host/database-adapters.js";
+export * from "./self-host/environment-builders.js";
 export * from "./self-host/manifest.js";
 export * from "./self-host/project-generator.js";
 export * from "./self-host/update.js";

package/dist/index.js

@@ -1,6 +1,7 @@
 export * from "./self-host/catalogue.js";
 export * from "./self-host/command.js";
 export * from "./self-host/database-adapters.js";
+export * from "./self-host/environment-builders.js";
 export * from "./self-host/manifest.js";
 export * from "./self-host/project-generator.js";
 export * from "./self-host/update.js";

package/dist/self-host/environment-builders.d.ts

@@ -0,0 +1,12 @@
+import { z } from "zod";
+export declare const selfHostEnvironmentBuilderSchema: z.ZodEnum<{
+    none: "none";
+    windows: "windows";
+    powershell: "powershell";
+    unix: "unix";
+    all: "all";
+}>;
+export type SelfHostEnvironmentBuilder = z.infer<typeof selfHostEnvironmentBuilderSchema>;
+export type SelfHostEnvironmentBuilderFile = "env-builder.mjs" | "env-builder.bat" | "env-builder.ps1" | "env-builder.sh";
+export declare function selfHostEnvironmentBuilderFiles(selection?: SelfHostEnvironmentBuilder): SelfHostEnvironmentBuilderFile[];
+//# sourceMappingURL=environment-builders.d.ts.map

package/dist/self-host/environment-builders.js

@@ -0,0 +1,25 @@
+import { z } from "zod";
+export const selfHostEnvironmentBuilderSchema = z.enum([
+    "none",
+    "windows",
+    "powershell",
+    "unix",
+    "all",
+]);
+export function selfHostEnvironmentBuilderFiles(selection = "none") {
+    selfHostEnvironmentBuilderSchema.parse(selection);
+    if (selection === "none")
+        return [];
+    const launchers = {
+        windows: "env-builder.bat",
+        powershell: "env-builder.ps1",
+        unix: "env-builder.sh",
+    };
+    return [
+        "env-builder.mjs",
+        ...(selection === "all"
+            ? Object.values(launchers)
+            : [launchers[selection]]),
+    ];
+}
+//# sourceMappingURL=environment-builders.js.map

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

@@ -1,7 +1,15 @@
 import { z } from "zod";
+import { type SelfHostEnvironmentBuilder } from "./environment-builders.js";
 import { type SelfHostCatalogue, type SelfHostDatabaseEngine } from "./catalogue.js";
 export declare const selfHostBuildManifestSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     schemaVersion: z.ZodLiteral<1>;
+    environmentBuilder: z.ZodOptional<z.ZodEnum<{
+        none: "none";
+        windows: "windows";
+        powershell: "powershell";
+        unix: "unix";
+        all: "all";
+    }>>;
     catalogueVersion: z.ZodNumber;
     core: z.ZodObject<{
         package: z.ZodString;
@@ -18,6 +26,13 @@ export declare const selfHostBuildManifestSchema: z.ZodDiscriminatedUnion<[z.Zod
     }, z.core.$strict>>;
 }, z.core.$strict>, z.ZodObject<{
     schemaVersion: z.ZodLiteral<2>;
+    environmentBuilder: z.ZodOptional<z.ZodEnum<{
+        none: "none";
+        windows: "windows";
+        powershell: "powershell";
+        unix: "unix";
+        all: "all";
+    }>>;
     databaseEngine: z.ZodOptional<z.ZodEnum<{
         postgresql: "postgresql";
         mysql: "mysql";
@@ -52,6 +67,6 @@ export declare const selfHostBuildManifestSchema: z.ZodDiscriminatedUnion<[z.Zod
     }, z.core.$strict>>;
 }, z.core.$strict>], "schemaVersion">;
 export type SelfHostBuildManifest = z.infer<typeof selfHostBuildManifestSchema>;
-export declare function createSelfHostBuildManifest(catalogue: SelfHostCatalogue, selectedModuleIds: readonly string[], databaseEngine?: SelfHostDatabaseEngine): SelfHostBuildManifest;
+export declare function createSelfHostBuildManifest(catalogue: SelfHostCatalogue, selectedModuleIds: readonly string[], databaseEngine?: SelfHostDatabaseEngine, environmentBuilder?: SelfHostEnvironmentBuilder): SelfHostBuildManifest;
 export declare function parseSelfHostBuildManifest(input: unknown, catalogue: SelfHostCatalogue): SelfHostBuildManifest;
 //# sourceMappingURL=manifest.d.ts.map

package/dist/self-host/manifest.js

@@ -1,6 +1,7 @@
 import semver from "semver";
 import { isDeepStrictEqual } from "node:util";
 import { z } from "zod";
+import { selfHostEnvironmentBuilderSchema, } from "./environment-builders.js";
 import { isSelfHostModuleCustomerSelectable, selfHostDatabaseEngineSchema, } from "./catalogue.js";
 const exactVersion = z
     .string()
@@ -23,6 +24,7 @@ const buildModuleSchema = z
 const selfHostBuildManifestV1Schema = z
     .object({
     schemaVersion: z.literal(1),
+    environmentBuilder: selfHostEnvironmentBuilderSchema.optional(),
     catalogueVersion: z.number().int().positive(),
     core: buildComponentSchema,
     generator: buildComponentSchema,
@@ -48,6 +50,7 @@ const buildModuleV2Schema = buildModuleSchema
 const selfHostBuildManifestV2Schema = z
     .object({
     schemaVersion: z.literal(2),
+    environmentBuilder: selfHostEnvironmentBuilderSchema.optional(),
     databaseEngine: selfHostDatabaseEngineSchema.optional(),
     catalogueVersion: z.number().int().positive(),
     core: buildComponentSchema,
@@ -82,15 +85,16 @@ export const selfHostBuildManifestSchema = z
         packages.add(module.package);
     }
 });
-export function createSelfHostBuildManifest(catalogue, selectedModuleIds, databaseEngine = "postgresql") {
+export function createSelfHostBuildManifest(catalogue, selectedModuleIds, databaseEngine = "postgresql", environmentBuilder = "none") {
     selfHostDatabaseEngineSchema.parse(databaseEngine);
+    selfHostEnvironmentBuilderSchema.parse(environmentBuilder);
     assertPublishedComponent(catalogue.core, "Helyx runtime");
     assertPublishedComponent(catalogue.generator, "Helyx generator");
     if (new Set(selectedModuleIds).size !== selectedModuleIds.length) {
         throw new Error("Self-host selection contains duplicate module IDs");
     }
     if (catalogue.schemaVersion === 2) {
-        return createSelfHostBuildManifestV2(catalogue, selectedModuleIds, databaseEngine);
+        return createSelfHostBuildManifestV2(catalogue, selectedModuleIds, databaseEngine, environmentBuilder);
     }
     if (databaseEngine !== "postgresql") {
         throw new Error("Legacy self-host catalogue supports PostgreSQL only");
@@ -115,6 +119,7 @@ export function createSelfHostBuildManifest(catalogue, selectedModuleIds, databa
     });
     return {
         schemaVersion: 1,
+        ...(environmentBuilder !== "none" ? { environmentBuilder } : {}),
         catalogueVersion: catalogue.catalogueVersion,
         core: {
             package: catalogue.core.package,
@@ -127,7 +132,7 @@ export function createSelfHostBuildManifest(catalogue, selectedModuleIds, databa
         modules,
     };
 }
-function createSelfHostBuildManifestV2(catalogue, selectedModuleIds, databaseEngine) {
+function createSelfHostBuildManifestV2(catalogue, selectedModuleIds, databaseEngine, environmentBuilder = "none") {
     const byId = new Map(catalogue.modules.map((module) => [module.id, module]));
     const explicitlySelected = new Set(selectedModuleIds);
     const modules = [];
@@ -189,6 +194,7 @@ function createSelfHostBuildManifestV2(catalogue, selectedModuleIds, databaseEng
         include(id);
     return {
         schemaVersion: 2,
+        ...(environmentBuilder !== "none" ? { environmentBuilder } : {}),
         ...(databaseEngine === "mysql" ? { databaseEngine } : {}),
         catalogueVersion: catalogue.catalogueVersion,
         core: {
@@ -218,13 +224,20 @@ export function parseSelfHostBuildManifest(input, catalogue) {
         const selectedModuleIds = manifest.modules
             .filter(({ moduleKind }) => moduleKind === "customer_feature")
             .map(({ id }) => id);
-        const expected = createSelfHostBuildManifestV2(catalogue, selectedModuleIds, manifest.databaseEngine ?? "postgresql");
+        const expected = createSelfHostBuildManifestV2(catalogue, selectedModuleIds, manifest.databaseEngine ?? "postgresql", manifest.environmentBuilder ?? "none");
         if (!isDeepStrictEqual({
             ...manifest,
+            environmentBuilder: manifest.environmentBuilder === "none"
+                ? undefined
+                : manifest.environmentBuilder,
             databaseEngine: manifest.databaseEngine === "postgresql"
                 ? undefined
                 : manifest.databaseEngine,
-        }, { ...expected, databaseEngine: expected.databaseEngine })) {
+        }, {
+            ...expected,
+            databaseEngine: expected.databaseEngine,
+            environmentBuilder: expected.environmentBuilder,
+        })) {
             throw new Error("Build manifest modules do not match the trusted catalogue dependency graph");
         }
         return expected;

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

@@ -2,6 +2,7 @@ import { createHash } from "node:crypto";
 import { spawn } from "node:child_process";
 import { mkdir, readFile, readdir, rm, stat, writeFile, } from "node:fs/promises";
 import { dirname, parse, resolve } from "node:path";
+import { selfHostEnvironmentBuilderFiles, } from "./environment-builders.js";
 import { isSelfHostModuleCustomerSelectable, } from "./catalogue.js";
 import { parseSelfHostBuildManifest, } from "./manifest.js";
 import { databaseAdaptersForCatalogue, } from "./database-adapters.js";
@@ -80,6 +81,7 @@ async function writeGeneratedFiles(targetDirectory, manifest, catalogue, databas
         engines: { node: ">=24 <27", npm: ">=11" },
         scripts: {
             setup: "helyx setup",
+            envbuilder: "helyx envbuilder",
             start: "helyx start",
             doctor: "helyx doctor",
             migrate: "helyx migrate",
@@ -95,7 +97,10 @@ async function writeGeneratedFiles(targetDirectory, manifest, catalogue, databas
     };
     await writeFile(resolve(targetDirectory, "package.json"), formatJson(packageJson), "utf8");
     await writeFile(resolve(targetDirectory, "helyx.modules.json"), formatJson(moduleCatalogue), "utf8");
-    for (const fileName of generatedFileNames) {
+    for (const fileName of [
+        ...generatedFileNames,
+        ...selfHostEnvironmentBuilderFiles(manifest.environmentBuilder),
+    ]) {
         const template = await readFile(fileName === "compose.yaml" && databaseEngine === "mysql"
             ? mysqlComposeTemplateUrl()
             : templateUrl(fileName), "utf8");
@@ -106,8 +111,13 @@ async function writeGeneratedFiles(targetDirectory, manifest, catalogue, databas
                 : template;
         if (fileName === ".env.example")
             validateEnvironmentTemplate(rendered, databaseEngine);
-        const content = normalizeCrLf(rendered);
-        await writeFile(resolve(targetDirectory, fileName), content, "utf8");
+        const content = fileName.endsWith(".sh")
+            ? rendered.replaceAll("\r\n", "\n")
+            : normalizeCrLf(rendered);
+        await writeFile(resolve(targetDirectory, fileName), content, {
+            encoding: "utf8",
+            mode: fileName.endsWith(".sh") ? 0o755 : 0o644,
+        });
     }
 }
 function renderEnvironmentExample(template, databaseEngine) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@helyx/cli",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "description": "Command-line tools for running and generating self-hosted Helyx deployments.",
   "keywords": [
     "helyx",

package/self-host-catalogue.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 2,
-  "catalogueVersion": 85,
+  "catalogueVersion": 86,
   "core": {
     "package": "@helyx/bot",
     "version": "1.5.3",
@@ -8,7 +8,7 @@
   },
   "generator": {
     "package": "@helyx/cli",
-    "version": "1.5.0",
+    "version": "1.6.0",
     "command": "helyx",
     "availability": "published"
   },

package/templates/self-host/README.md

@@ -20,6 +20,31 @@ The matching offline operator and module-author documentation is listed in
 
 ## Choose a runtime path
 
+### Optional guided environment builder
+
+Run `npm run envbuilder` to create or update `.env` by answering questions.
+This optional command is available after `npm ci`; normal setup and startup do
+not run it. If you selected additional environment builders when downloading
+your starter, you can also use these included files before package installation:
+
+- Windows: double-click `env-builder.bat`, or run `.\env-builder.ps1` in PowerShell.
+- macOS and Linux: run `sh ./env-builder.sh` in a terminal.
+
+No additional builder files are included by default. Each platform selection
+includes its matching script and the shared `env-builder.mjs`; selecting all
+builders includes every platform script. The npm command is always included.
+
+The builder detects the starter's database selection, checks input format, and
+asks whether to enable server-specific slash commands for your server IDs.
+Database URLs and bot tokens are visible while you type or paste; saved values
+remain masked in prompts and the review summary. Database passwords are hidden
+while typing. Existing encryption keys and custom settings are retained.
+
+Nothing is saved until you type `SAVE`. The builder makes no connection tests,
+installs no packages and starts no services. It is optional: `setup`, `doctor`,
+installation and startup do not launch it. You may still edit `.env` manually.
+Continue with the installation and runtime checks for your chosen path below.
+
 ### 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 one local or hosted supported database. Helyx does not require Docker.

package/templates/self-host/env-builder.bat

@@ -0,0 +1,14 @@
+@echo off
+setlocal DisableDelayedExpansion
+title Helyx Environment Builder
+where node >nul 2>nul
+if errorlevel 1 (
+  echo Node.js 24 or newer is required. Install Node.js and run this file again.
+  pause
+  exit /b 1
+)
+node "%~dp0env-builder.mjs" %*
+set "builder_exit=%errorlevel%"
+echo.
+pause
+exit /b %builder_exit%

package/templates/self-host/env-builder.mjs

@@ -0,0 +1,741 @@
+import { randomBytes } from "node:crypto";
+import {
+  link,
+  lstat,
+  open,
+  readFile,
+  readdir,
+  rename,
+  unlink,
+} from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { createInterface } from "node:readline";
+import { Writable } from "node:stream";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { parseEnv } from "node:util";
+
+const scriptDirectory = dirname(fileURLToPath(import.meta.url));
+class WizardError extends Error {}
+const encryptionKey = "HELYX_DATA_ENCRYPTION_KEY";
+const secretFields = new Set([
+  encryptionKey,
+  "DATABASE_URL",
+  "DISCORD_TOKEN",
+  "PGPASSWORD",
+  "POSTGRES_PASSWORD",
+]);
+const placeholder =
+  /replace[- ]|12345678901234567|^mysql:\/\/user:password@host/iu;
+const safeDisplay = (value) => value.replace(/[\p{Cc}\p{Cf}]/gu, "?");
+
+export function maskSecret(value) {
+  const chars = Array.from(value);
+  if (chars.length <= 4) return "*".repeat(chars.length);
+  if (chars.length === 5) return `***${safeDisplay(chars.slice(-2).join(""))}`;
+  const prefix = Math.min(5, chars.length - 4);
+  return `${safeDisplay(chars.slice(0, prefix).join(""))}${"*".repeat(chars.length - prefix - 3)}${safeDisplay(chars.slice(-3).join(""))}`;
+}
+
+async function optionalRead(path) {
+  try {
+    const info = await lstat(path);
+    if (!info.isFile() || info.isSymbolicLink())
+      throw new WizardError(
+        "Expected a regular file; symbolic links are not supported.",
+      );
+    return await readFile(path, "utf8");
+  } catch (error) {
+    if (error.code === "ENOENT" || error.code === "ENOTDIR") return null;
+    throw error;
+  }
+}
+
+export async function isStarter(directory) {
+  const example = await optionalRead(join(directory, ".env.example"));
+  if (example === null) return false;
+  const packageText = await optionalRead(join(directory, "package.json"));
+  if (!packageText) return false;
+  try {
+    return JSON.parse(packageText).name === "helyx-self-hosted";
+  } catch {
+    return false;
+  }
+}
+
+export async function discoverStarters(roots) {
+  const candidates = new Set();
+  const inspected = new Set();
+  for (const root of new Set(roots.map((path) => resolve(path)))) {
+    let entries;
+    try {
+      entries = await readdir(root, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    const paths = [
+      root,
+      ...entries
+        .filter(
+          (entry) =>
+            entry.isDirectory() &&
+            !entry.name.startsWith(".") &&
+            entry.name !== "node_modules",
+        )
+        .map((entry) => join(root, entry.name)),
+    ];
+    for (const path of paths) {
+      const identity = process.platform === "win32" ? path.toLowerCase() : path;
+      if (inspected.has(identity)) continue;
+      inspected.add(identity);
+      try {
+        if (await isStarter(path)) candidates.add(path);
+      } catch {
+        // An inaccessible neighbouring folder does not prevent manual selection.
+      }
+    }
+  }
+  return [...candidates].sort();
+}
+
+export function validateDatabaseUrl(value, engine) {
+  try {
+    if (/\s/u.test(value) || placeholder.test(value)) throw new WizardError();
+    const url = new URL(value);
+    const protocols =
+      engine === "mysql" ? ["mysql:"] : ["postgres:", "postgresql:"];
+    if (
+      !protocols.includes(url.protocol) ||
+      !url.hostname ||
+      url.pathname.length < 2 ||
+      url.hash ||
+      (url.port && Number(url.port) < 1)
+    )
+      throw new WizardError();
+    decodeURIComponent(url.username);
+    decodeURIComponent(url.password);
+  } catch {
+    throw new WizardError(
+      `Enter a ${engine} URL with a host, database name and valid port. Percent-encode special characters in credentials.`,
+    );
+  }
+}
+
+// Use single quotes to retain #, $, spaces and backslashes literally in Node
+// and Compose. Unusual mixed-quote values require manual editing, not guessing.
+export function encodeValue(value) {
+  if (/[\p{Cc}\p{Cf}]/u.test(value))
+    throw new WizardError(
+      "Use a single-line value without control characters.",
+    );
+  if (!value.includes("'")) return `'${value}'`;
+  if (!/["\\$]/u.test(value)) return `"${value}"`;
+  throw new WizardError(
+    "This value needs manual .env quoting. For URLs, percent-encode quote characters.",
+  );
+}
+
+function records(content) {
+  const lines = content.match(/[^\r\n]*(?:\r\n|\n|$)/gu)?.filter(Boolean) ?? [];
+  const result = [];
+  for (let index = 0; index < lines.length; index++) {
+    let text = lines[index];
+    const match = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)/u.exec(
+      text,
+    );
+    const key = match?.[1];
+    const quote = match?.[2]?.[0];
+    let comment = match?.[2]?.match(/\s+#.*$/u)?.[0] ?? "";
+    if (quote === "'" || quote === '"' || quote === "`") {
+      let tail = match[2].slice(1);
+      while (!tail.includes(quote) && index + 1 < lines.length) {
+        const next = lines[++index];
+        text += next;
+        tail += next;
+      }
+      if (!tail.includes(quote))
+        throw new WizardError(
+          "The environment file has an unclosed quoted value. Correct it before continuing.",
+        );
+      comment =
+        tail.slice(tail.indexOf(quote) + 1).match(/^[\t ]*#.*$/mu)?.[0] ?? "";
+    }
+    result.push({ key, text, comment });
+  }
+  return result;
+}
+
+export function updateEnvironment(content, changes) {
+  const newline = content.includes("\r\n") ? "\r\n" : "\n";
+  const remaining = new Map(Object.entries(changes));
+  const seen = new Set();
+  const output = records(content)
+    .map(({ key, text, comment }) => {
+      if (!Object.hasOwn(changes, key)) return text;
+      if (seen.has(key)) return ""; // Remove duplicate active assignments.
+      seen.add(key);
+      remaining.delete(key);
+      return `${key}=${encodeValue(changes[key])}${comment}${newline}`;
+    })
+    .join("");
+  return (
+    output +
+    (remaining.size && output && !output.endsWith("\n") ? newline : "") +
+    [...remaining]
+      .map(([key, value]) => `${key}=${encodeValue(value)}${newline}`)
+      .join("")
+  );
+}
+
+const environmentGroups = [
+  [
+    "INSTALLATION",
+    /^(?:HELYX_RUNTIME_PROFILE|HELYX_DEPLOYMENT_ENVIRONMENT|NODE_ENV)$/u,
+  ],
+  ["DISCORD BOT", /^(?:DISCORD_TOKEN|DISCORD_CLIENT_ID)$/u],
+  [
+    "DISCORD SERVER COMMANDS",
+    /^(?:HELYX_GUILD_COMMAND_|HELYX_GLOBAL_COMMAND_MODE)/u,
+  ],
+  [
+    "DISCORD GATEWAY INTENTS",
+    /^HELYX_(?:MESSAGE_CONTENT_ENABLED|GUILD_MEMBERS_ENABLED)$/u,
+  ],
+  ["DATABASE CONNECTION", /^DATABASE_|^HELYX_DATABASE_STARTUP_MODE$/u],
+  ["BUNDLED DOCKER POSTGRESQL", /^(?:PGUSER|PGPASSWORD|POSTGRES_)/u],
+  [
+    "DASHBOARD AND OWNERS",
+    /^(?:HELYX_CLOUD_CONNECT_ENABLED|HELYX_DASHBOARD_PUBLIC_URL|HELYX_OWNER_USER_IDS)$/u,
+  ],
+  ["DATA ENCRYPTION - KEEP THIS KEY", /^HELYX_DATA_ENCRYPTION_KEY$/u],
+  ["LOGGING", /^LOG_LEVEL$/u],
+  ["AUTO MODERATION", /^HELYX_AUTOMOD_/u],
+  ["SHARDING - ADVANCED", /^HELYX_SHARD_/u],
+  ["MODULE SELECTION", /^HELYX_MODULE_/u],
+  [
+    "PRIVATE CONTROL - ADVANCED",
+    /^HELYX_BOT_CONTROL_|^HELYX_HOSTED_MODERATION_ENABLED$|^HELYX_GUILD_RECONCILIATION_INTERVAL_SECONDS$/u,
+  ],
+  ["CLOUD CONNECT - ADVANCED", /^HELYX_CLOUD_/u],
+  ["OAUTH - ADVANCED", /^HELYX_OAUTH_/u],
+  ["STATUS REPORTING - OPTIONAL", /^HELYX_STATUS_|^CF_ACCESS_/u],
+  [
+    "INTERNAL DEVELOPMENT - OPTIONAL",
+    /^(?:DISCORD_INTERNAL_GUILD_ID|APPROVED_ROLES)$/u,
+  ],
+  ["CUSTOM SETTINGS", /./u],
+];
+const oldHeadings = new Set([
+  "REQUIRED — EDIT THESE VALUES",
+  "Discord",
+  "Database",
+  "OPTIONAL EVERYDAY SETTINGS",
+  "SHARDING: OFF BY DEFAULT",
+  "ADVANCED INTEGRATIONS — EDIT ONLY WHEN NEEDED",
+  "DANGER ZONE — HELYX-MANAGED VALUES, DO NOT EDIT",
+  "Runtime mode",
+  "Helyx self-hosted environment",
+  "Keep this file private. Lines starting with # are comments.",
+]);
+
+export function formatEnvironment(content) {
+  const newline = content.includes("\r\n") ? "\r\n" : "\n";
+  const groups = environmentGroups.map(() => []);
+  let pending = [];
+  let previousGroup;
+  const append = (index, lines) => {
+    const text = lines.join("\n").trim();
+    if (!text) return;
+    if (
+      groups[index].length &&
+      text.startsWith("#") &&
+      !/^#\s*[A-Za-z_][A-Za-z0-9_]*\s*=/u.test(text)
+    )
+      groups[index].push("");
+    groups[index].push(text);
+  };
+  for (const record of records(content)) {
+    const text = record.text.replace(/\r\n/gu, "\n").replace(/\n$/u, "");
+    const heading = text.match(/^#\s*(.*?)\s*$/u)?.[1];
+    if (
+      heading !== undefined &&
+      (oldHeadings.has(heading) ||
+        /^=+$/u.test(heading) ||
+        environmentGroups.some(([title]) => heading === title))
+    )
+      continue;
+    const key =
+      record.key ?? text.match(/^\s*#\s*([A-Za-z_][A-Za-z0-9_]*)\s*=/u)?.[1];
+    if (!key) {
+      if (!text.trim() && pending.length && previousGroup !== undefined) {
+        append(previousGroup, pending);
+        pending = [];
+      } else if (text.trim()) pending.push(text);
+      continue;
+    }
+    const group = environmentGroups.findIndex(([, pattern]) =>
+      pattern.test(key),
+    );
+    append(group, [...pending, text]);
+    pending = [];
+    previousGroup = group;
+  }
+  if (pending.length) append(previousGroup ?? groups.length - 1, pending);
+  const divider =
+    "# ============================================================================";
+  const output =
+    [
+      "# Helyx self-hosted environment\n# Keep this file private. Lines starting with # are comments.",
+      ...groups.flatMap((lines, index) =>
+        lines.length
+          ? [
+              `${divider}\n# ${environmentGroups[index][0]}\n${divider}\n\n${lines.join("\n")}`,
+            ]
+          : [],
+      ),
+    ].join("\n\n\n") + "\n";
+  const formatted = output.replace(/\n/gu, newline);
+  const before = parseEnv(content);
+  const after = parseEnv(formatted);
+  if (
+    Object.keys(before).length !== Object.keys(after).length ||
+    Object.entries(before).some(([key, value]) => after[key] !== value)
+  )
+    throw new WizardError(
+      "The environment could not be regrouped without changing values. No changes were saved.",
+    );
+  return formatted;
+}
+
+export async function saveEnvironment(directory, original, content) {
+  const destination = join(directory, ".env");
+  const temporary = join(
+    directory,
+    `.env-builder-${randomBytes(8).toString("hex")}.tmp`,
+  );
+  let handle;
+  try {
+    if ((await optionalRead(destination)) !== original)
+      throw new WizardError(
+        "The .env file changed while the wizard was open. Run the builder again.",
+      );
+    handle = await open(temporary, "wx", 0o600);
+    await handle.writeFile(content, "utf8");
+    await handle.sync();
+    await handle.close();
+    handle = undefined;
+    if ((await optionalRead(destination)) !== original)
+      throw new WizardError(
+        "The .env file changed while the wizard was open. Run the builder again.",
+      );
+    if (original === null) {
+      // Publish the complete file exclusively, without a partially written .env.
+      await link(temporary, destination);
+    } else {
+      await rename(temporary, destination);
+    }
+  } finally {
+    await handle?.close();
+    await unlink(temporary).catch((error) => {
+      if (error.code !== "ENOENT") throw error;
+    });
+  }
+}
+
+export function terminalIO() {
+  return {
+    print: (text) => console.log(text),
+    ask: (prompt, { secret = false } = {}) =>
+      new Promise((accept, reject) => {
+        const muted = new Writable({
+          write(_chunk, _encoding, callback) {
+            callback();
+          },
+        });
+        const rl = createInterface({
+          input: process.stdin,
+          output: secret ? muted : process.stdout,
+          terminal: true,
+          historySize: 0,
+        });
+        let answered = false;
+        if (secret) process.stdout.write(prompt);
+        rl.on("SIGINT", () => {
+          rl.close();
+        });
+        rl.on("close", () => {
+          if (!answered)
+            reject(new WizardError("Cancelled. No changes were saved."));
+        });
+        rl.question(secret ? "" : prompt, (answer) => {
+          answered = true;
+          rl.close();
+          if (secret) process.stdout.write("\n");
+          accept(answer.trim());
+        });
+      }),
+  };
+}
+
+export async function runWizard({
+  roots = [process.cwd(), scriptDirectory],
+  directory,
+  io = terminalIO(),
+} = {}) {
+  io.print("\nHELYX ENVIRONMENT BUILDER\n");
+  io.print(
+    "Credentials stay on this computer. No uploads, telemetry or connection tests.\nDatabase URL and Discord token input is visible so you can check typing and pasting. Password input is hidden.\nSaved secrets stay masked in prompts and the summary. Nothing is saved until you confirm.\nPress Ctrl+C at any question to cancel.\n",
+  );
+  if (!directory) {
+    const candidates = await discoverStarters(roots);
+    if (candidates.length === 1) directory = candidates[0];
+    else if (candidates.length > 1) {
+      io.print("Starter folders found:");
+      candidates.forEach((candidate, index) =>
+        io.print(`${index + 1}. ${safeDisplay(candidate)}`),
+      );
+      while (!directory) {
+        const selected = await io.ask(
+          "Choose a starter number, or P to enter a path: ",
+        );
+        if (selected.toLowerCase() === "p") break;
+        if (/^[1-9]\d*$/u.test(selected))
+          directory = candidates[Number(selected) - 1];
+      }
+    }
+    while (!directory) {
+      const answer = await io.ask(
+        "Paste or drag your extracted starter folder here: ",
+      );
+      const candidate = resolve(answer.replace(/^"(.*)"$/u, "$1"));
+      if (await isStarter(candidate)) directory = candidate;
+      else
+        io.print(
+          "That folder needs a Helyx starter package.json and .env.example. The Helyx source repository is not a starter.",
+        );
+    }
+  }
+  directory = resolve(directory);
+  if (!(await isStarter(directory)))
+    throw new WizardError(
+      "Choose a downloaded Helyx starter folder containing package.json and .env.example.",
+    );
+  const original = await optionalRead(join(directory, ".env"));
+  const template = await readFile(join(directory, ".env.example"), "utf8");
+  const existing = parseEnv(original ?? "");
+  const defaults = parseEnv(template);
+  const values = { ...defaults, ...existing };
+  const changes = {};
+  io.print(
+    `Starter: ${safeDisplay(directory)}\n${original === null ? "Creating a new .env." : "Updating the existing .env; Enter keeps each current value."}`,
+  );
+  const askValue = async (
+    key,
+    label,
+    {
+      secret = false,
+      visibleInput = false,
+      validate = () => {},
+      fallback,
+      optional = false,
+    } = {},
+  ) => {
+    const current = fallback ?? values[key] ?? "";
+    const display = current
+      ? secret
+        ? maskSecret(current)
+        : safeDisplay(current)
+      : "none";
+    for (;;) {
+      const answer = await io.ask(
+        `${label} [${display}]${optional ? " (Enter keeps; - clears)" : " (Enter keeps)"}: `,
+        { secret: secret && !visibleInput },
+      );
+      const value = optional && answer === "-" ? "" : answer || current;
+      try {
+        if (placeholder.test(value))
+          throw new WizardError(
+            "Replace the example placeholder with your own value.",
+          );
+        if (!optional && !value) throw new WizardError("A value is required.");
+        encodeValue(value);
+        validate(value);
+        values[key] = value;
+        if (value !== existing[key]) changes[key] = value;
+        return value;
+      } catch (error) {
+        io.print(error.message);
+      }
+    }
+  };
+  const choice = (options) => (value) => {
+    if (!options.includes(value))
+      throw new WizardError(`Choose ${options.join(" or ")}.`);
+  };
+  const previousEngine = values.DATABASE_ENGINE;
+  const engine = await askValue(
+    "DATABASE_ENGINE",
+    "Database engine (change if needed)",
+    { validate: choice(["postgresql", "mysql"]) },
+  );
+  if (engine !== defaults.DATABASE_ENGINE)
+    io.print(
+      "DATABASE CHANGED: this tool updates .env only. Use a matching starter before running Helyx; Compose and module files are not converted.",
+    );
+  const bundledAvailable =
+    engine === "postgresql" &&
+    defaults.DATABASE_ENGINE === "postgresql" &&
+    (await optionalRead(join(directory, "compose.yaml"))) !== null &&
+    Boolean(defaults.POSTGRES_PASSWORD);
+  let databaseMode = "external";
+  if (bundledAvailable) {
+    for (;;) {
+      databaseMode =
+        (await io.ask(
+          `Database source: bundled Docker PostgreSQL or external URL [${values.DATABASE_URL === "postgresql://database:5432/helyx" ? "bundled" : "external"}]: `,
+        )) ||
+        (values.DATABASE_URL === "postgresql://database:5432/helyx"
+          ? "bundled"
+          : "external");
+      if (["bundled", "external"].includes(databaseMode)) break;
+      io.print("Choose bundled or external.");
+    }
+  }
+  if (databaseMode === "bundled") {
+    io.print(
+      "Bundled PostgreSQL: use the existing database username/name; changing a password does not update an already-initialised database volume.",
+    );
+    const password = await askValue(
+      "POSTGRES_PASSWORD",
+      "Database password (16+ letters, digits, _ or -)",
+      {
+        secret: true,
+        fallback:
+          existing.POSTGRES_PASSWORD &&
+          !placeholder.test(existing.POSTGRES_PASSWORD)
+            ? existing.POSTGRES_PASSWORD
+            : randomBytes(24).toString("hex"),
+        validate: (value) => {
+          if (!/^[A-Za-z0-9_-]{16,}$/u.test(value))
+            throw new WizardError(
+              "Use at least 16 letters, digits, underscores or hyphens.",
+            );
+        },
+      },
+    );
+    const user = values.POSTGRES_USER || "helyx";
+    const name = values.POSTGRES_DB || "helyx";
+    if (!/^[A-Za-z0-9_-]+$/u.test(user) || !/^[A-Za-z0-9_-]+$/u.test(name))
+      throw new WizardError(
+        "The existing Docker database user/name needs manual configuration.",
+      );
+    Object.assign(changes, {
+      PGPASSWORD: password,
+      PGUSER: user,
+      POSTGRES_USER: user,
+      POSTGRES_DB: name,
+      DATABASE_URL: "postgresql://database:5432/helyx",
+      DATABASE_SSL: "disable",
+    });
+  } else {
+    await askValue(
+      "DATABASE_URL",
+      "Database connection URL (typing and paste visible)",
+      {
+        secret: true,
+        visibleInput: true,
+        fallback:
+          engine !== previousEngine ||
+          (values.DATABASE_URL ?? "").includes("://database:")
+            ? ""
+            : values.DATABASE_URL,
+        validate: (value) => validateDatabaseUrl(value, engine),
+      },
+    );
+    io.print(
+      "SSL: disable = no TLS; require = TLS without certificate verification; verify-full = TLS with certificate verification. Use your provider's requirement.",
+    );
+    await askValue("DATABASE_SSL", "Database SSL mode", {
+      fallback: existing.DATABASE_SSL ?? "verify-full",
+      validate: choice(["disable", "require", "verify-full"]),
+    });
+  }
+  await askValue("DISCORD_CLIENT_ID", "Discord application ID", {
+    validate: (value) => {
+      if (!/^\d{17,20}$/u.test(value))
+        throw new WizardError("Enter the 17-20 digit Discord application ID.");
+    },
+  });
+  io.print(
+    "Enter the Discord server ID for your bot's server-specific slash commands. For several servers, separate IDs with commas. You can choose whether to enable these commands next.",
+  );
+  const validateGuildIds = (value) => {
+    if (value && !/^\d{17,20}(?:,\d{17,20})*$/u.test(value))
+      throw new WizardError(
+        "Use 17-20 digit Discord server IDs, separated by commas without spaces.",
+      );
+  };
+  let guildIds = await askValue(
+    "HELYX_GUILD_COMMAND_WRITE_GUILD_IDS",
+    "Discord server (guild) ID(s), optional",
+    {
+      optional: true,
+      validate: validateGuildIds,
+    },
+  );
+  const currentCommandChoice =
+    values.HELYX_GUILD_COMMAND_WRITES_ENABLED === "true" ? "yes" : "no";
+  let enableServerCommands;
+  for (;;) {
+    const answer =
+      (
+        await io.ask(
+          `Enable server-specific slash commands for these servers? Yes/No [${currentCommandChoice}]: `,
+        )
+      ).toLowerCase() || currentCommandChoice;
+    if (["yes", "y", "no", "n"].includes(answer)) {
+      enableServerCommands = answer === "yes" || answer === "y";
+      break;
+    }
+    io.print("Choose Yes or No. Enter keeps the choice shown in brackets.");
+  }
+  if (enableServerCommands) {
+    if (!guildIds) {
+      io.print(
+        "At least one Discord server ID is needed to enable server-specific slash commands.",
+      );
+      guildIds = await askValue(
+        "HELYX_GUILD_COMMAND_WRITE_GUILD_IDS",
+        "Discord server (guild) ID(s)",
+        { validate: validateGuildIds },
+      );
+    }
+    Object.assign(changes, {
+      HELYX_GUILD_COMMAND_WRITE_GUILD_IDS: guildIds,
+      HELYX_GUILD_COMMAND_WRITES_ENABLED: "true",
+      HELYX_GUILD_COMMAND_WRITE_SCOPE: "allowlist",
+      HELYX_GLOBAL_COMMAND_MODE: "platform-only",
+    });
+    io.print(
+      "Server-specific slash commands will be enabled for the listed servers when Helyx starts. Core commands remain global.",
+    );
+  } else {
+    changes.HELYX_GUILD_COMMAND_WRITES_ENABLED = "false";
+    io.print("Server-specific slash command registration will be disabled.");
+  }
+  await askValue(
+    "DISCORD_TOKEN",
+    "Discord bot token (typing and paste visible)",
+    {
+      secret: true,
+      visibleInput: true,
+      validate: (value) => {
+        if (/\s/u.test(value) || /^(?:Bot|Bearer)\b/iu.test(value))
+          throw new WizardError(
+            "Paste the bot token only, without spaces or a Bot/Bearer prefix.",
+          );
+      },
+    },
+  );
+  io.print(
+    "Enable gateway intents only if required by your modules and enabled in the Discord Developer Portal.",
+  );
+  for (const [key, label] of [
+    ["HELYX_GUILD_MEMBERS_ENABLED", "Server Members Intent (true/false)"],
+    ["HELYX_MESSAGE_CONTENT_ENABLED", "Message Content Intent (true/false)"],
+    [
+      "HELYX_CLOUD_CONNECT_ENABLED",
+      "Allow optional Cloud Connect pairing (true/false)",
+    ],
+  ]) {
+    await askValue(key, label, { validate: choice(["true", "false"]) });
+  }
+  await askValue(
+    "HELYX_OWNER_USER_IDS",
+    "Additional owner Discord IDs (comma-separated, optional)",
+    {
+      optional: true,
+      validate: (value) => {
+        if (
+          value &&
+          (!/^\d{17,20}(?:,\d{17,20})*$/u.test(value) ||
+            value.split(",").length > 20)
+        )
+          throw new WizardError(
+            "Use comma-separated 17-20 digit user IDs, without spaces.",
+          );
+      },
+    },
+  );
+  if (existing[encryptionKey] && !placeholder.test(existing[encryptionKey])) {
+    const key = existing[encryptionKey];
+    if (
+      Buffer.from(key, "base64").length !== 32 ||
+      Buffer.from(key, "base64").toString("base64") !== key
+    )
+      throw new WizardError(
+        "The existing data-encryption key has an invalid format. It was not replaced; restore the correct key before continuing.",
+      );
+    io.print(`Keeping existing data-encryption key: ${maskSecret(key)}`);
+  } else changes[encryptionKey] = randomBytes(32).toString("base64");
+  Object.assign(changes, {
+    HELYX_RUNTIME_PROFILE: "self-hosted",
+    HELYX_DEPLOYMENT_ENVIRONMENT: "self-hosted",
+  });
+  if (engine === "mysql") Object.assign(changes, { HELYX_SHARD_MODE: "off" });
+  const updated = formatEnvironment(
+    updateEnvironment(original ?? template, changes),
+  );
+  for (const [key, value] of Object.entries(changes))
+    if (parseEnv(updated)[key] !== value)
+      throw new WizardError(
+        "The output could not be encoded safely. No changes were saved.",
+      );
+  io.print("\nReview changes (secrets masked):");
+  for (const [key, value] of Object.entries(changes))
+    io.print(
+      `  ${key}: ${existing[key] === undefined ? "not set" : secretFields.has(key) ? maskSecret(existing[key]) : safeDisplay(existing[key])} -> ${secretFields.has(key) ? maskSecret(value) : safeDisplay(value) || "none"}`,
+    );
+  io.print(`\nSave to: ${safeDisplay(join(directory, ".env"))}`);
+  if (
+    (await io.ask("Save this .env? Type SAVE to confirm: ")).toUpperCase() !==
+    "SAVE"
+  ) {
+    io.print("Cancelled. No changes were saved.");
+    return { saved: false, directory };
+  }
+  await saveEnvironment(directory, original, updated);
+  io.print(
+    "\nSaved .env. Configuration format checked; no database or Discord connection was tested.\nKeep this file and its data-encryption key private and backed up.\nThe builder did not install packages, start Helyx or change other starter files.",
+  );
+  return { saved: true, directory };
+}
+
+export async function runEnvironmentBuilder(directory) {
+  if (Number(process.versions.node.split(".")[0]) < 24) {
+    console.error("Node.js 24 or newer is required.");
+    process.exitCode = 1;
+  } else if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    console.error(
+      "Open this builder in an interactive terminal or use the launcher for your platform.",
+    );
+    process.exitCode = 1;
+  } else {
+    try {
+      await runWizard({ directory });
+    } catch (error) {
+      console.error(
+        error instanceof WizardError
+          ? error.message
+          : "The builder stopped without completing. Check file access and the starter's environment syntax. No credential values are included in errors.",
+      );
+      process.exitCode = 1;
+    }
+  }
+}
+
+if (
+  process.argv[1] &&
+  import.meta.url === pathToFileURL(resolve(process.argv[1])).href
+) {
+  await runEnvironmentBuilder(process.argv[2]);
+}

package/templates/self-host/env-builder.ps1

@@ -0,0 +1,13 @@
+param(
+    [Parameter(ValueFromRemainingArguments = $true)]
+    [string[]]$BuilderArguments
+)
+
+$ErrorActionPreference = 'Stop'
+if (-not (Get-Command node -ErrorAction SilentlyContinue)) {
+    Write-Error 'Node.js 24 or newer is required. Install Node.js and run this file again.'
+    exit 1
+}
+
+& node (Join-Path $PSScriptRoot 'env-builder.mjs') @BuilderArguments
+exit $LASTEXITCODE

package/templates/self-host/env-builder.sh

@@ -0,0 +1,10 @@
+#!/bin/sh
+set -eu
+
+if ! command -v node >/dev/null 2>&1; then
+  printf '%s\n' 'Node.js 24 or newer is required. Install Node.js and run this file again.' >&2
+  exit 1
+fi
+
+builder_directory=$(CDPATH= cd -P "$(dirname "$0")" && pwd)
+exec node "$builder_directory/env-builder.mjs" "$@"