@helyx/cli 1.5.0 → 1.6.1

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

@@ -0,0 +1,747 @@
+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],
+  ["SHARDING - ADVANCED", /^HELYX_SHARD_/u],
+  ["MODULE SELECTION", /^HELYX_MODULE_/u],
+  ["CUSTOM SETTINGS", /./u],
+];
+const omittedExampleSetting =
+  /^(?:HELYX_AUTOMOD_|HELYX_BOT_CONTROL_|HELYX_HOSTED_MODERATION_ENABLED$|HELYX_GUILD_RECONCILIATION_INTERVAL_SECONDS$|HELYX_CLOUD_(?!CONNECT_ENABLED$)|HELYX_OAUTH_|HELYX_STATUS_|CF_ACCESS_|DISCORD_INTERNAL_GUILD_ID$|APPROVED_ROLES$)/u;
+const oldHeadings = new Set([
+  "AUTO MODERATION",
+  "PRIVATE CONTROL - ADVANCED",
+  "CLOUD CONNECT - ADVANCED",
+  "OAUTH - ADVANCED",
+  "STATUS REPORTING - OPTIONAL",
+  "INTERNAL DEVELOPMENT - OPTIONAL",
+  "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, { template = false } = {}) {
+  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 && omittedExampleSetting.test(key) && (template || !record.key)) {
+      pending = [];
+      continue;
+    }
+    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);
+  if (template)
+    for (const key of Object.keys(before))
+      if (omittedExampleSetting.test(key)) delete before[key];
+  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 = formatEnvironment(
+    await readFile(join(directory, ".env.example"), "utf8"),
+    { template: true },
+  );
+  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]);
+}