@helyx/cli 0.2.2 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## 0.3.0
+
+### Minor Changes
+
+- 43704ad: Add the reviewed self-host update workflow with read-only checking, managed-file
+  backups, coherent exact dependency and lockfile updates, failure restoration,
+  generated project scripts, and current upgrade guidance.
+
+  First-run setup now also generates a private local data-encryption key when it
+  is missing, without displaying it or replacing an existing key.
+
+  Reorganise the generated environment template so required customer values are
+  first and Helyx-managed danger-zone settings are clearly separated.
+
+  Enable the unpaired Cloud Connect connector in generated starters so linking
+  requires only the one-use code rather than an additional environment edit.
+
+### Patch Changes
+
+- Updated dependencies [18265bc]
+- Updated dependencies [b0f1932]
+  - @helyx/database@0.2.1
+  - @helyx/bot@0.2.2
+
 ## 0.2.2
 
 ### Patch Changes

package/README.md

@@ -8,10 +8,14 @@ helyx start
 helyx migrate
 helyx doctor
 helyx self-host init --manifest ./helyx-build.json --output ./helyx
+helyx self-host update --check
+helyx self-host update --confirm
 ```
 
 `setup` safely creates `.env` from a generated starter's `.env.example`, never overwrites existing configuration and reports whether Docker Compose is available. Direct Node.js operation remains fully supported with a local or hosted PostgreSQL database. `start` loads local configuration without overriding hosting-platform variables and performs the production bot bootstrap, including database and installed-module migrations. `migrate` applies only core migrations and exits. `doctor` validates the complete bot environment, PostgreSQL connectivity, immutable core migration history and configured module package metadata without logging in to Discord or modifying the database.
 
 `self-host init` validates a build manifest against the reviewed catalogue shipped with this exact CLI version, creates a new starter-project directory, pins the runtime and selected official modules, generates a lockfile with lifecycle scripts disabled, and writes checksums. Add `--install` only when the dependencies should also be installed locally. Unknown, unpublished, duplicated or modified package selections fail closed.
 
+`self-host update --check` reads the current project and the reviewed catalogue from `api.helyx.gg`, then reports the complete compatible release-set change without writing files. `--confirm` backs up the managed metadata under `.helyx/backups`, updates exact core, CLI and selected live-module versions together, refreshes and validates the lockfile with lifecycle scripts disabled, and restores the original metadata if generation fails. Run `npm ci` and `npm run doctor` after applying an update. The updater never changes `.env` or customer database data.
+
 The package is published under the Helyx Source Available Licence. Generated projects contain deployment configuration and exact public npm dependencies; they do not contain Helyx source code or credentials.

package/dist/cli.js

@@ -42,8 +42,10 @@ catch (error) {
 async function setup() {
     const result = await setupSelfHostEnvironment();
     console.log(result.created
-        ? "Created .env from .env.example. Existing files were not overwritten."
-        : "The existing .env file was left unchanged.");
+        ? "Created .env from .env.example and generated its private data-encryption key."
+        : result.dataEncryptionKeyCreated
+            ? "Added the missing private data-encryption key to the existing .env file."
+            : "The existing .env file and data-encryption key were left unchanged.");
     if (result.dockerComposeAvailable) {
         console.log("Docker Compose is available. You may use the included bot and PostgreSQL services.");
     }
@@ -102,6 +104,10 @@ Commands:
   doctor   Validate environment, database schema and module packages
   self-host init --manifest <path> [--output <path>] [--install]
            Generate a self-hosted starter project from a reviewed manifest
+  self-host update --check [--project <path>]
+           Check the current project against the reviewed release set
+  self-host update --confirm [--project <path>]
+           Back up and update exact Helyx dependencies and the lockfile
   help     Show this help`);
 }
 //# sourceMappingURL=cli.js.map

package/dist/index.d.ts

@@ -2,5 +2,6 @@ export * from "./self-host/catalogue.js";
 export * from "./self-host/command.js";
 export * from "./self-host/manifest.js";
 export * from "./self-host/project-generator.js";
+export * from "./self-host/update.js";
 export * from "./setup.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -2,5 +2,6 @@ export * from "./self-host/catalogue.js";
 export * from "./self-host/command.js";
 export * from "./self-host/manifest.js";
 export * from "./self-host/project-generator.js";
+export * from "./self-host/update.js";
 export * from "./setup.js";
 //# sourceMappingURL=index.js.map

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

@@ -1,9 +1,16 @@
 import { type GeneratedSelfHostProject } from "./project-generator.js";
+import { type SelfHostUpdatePlan } from "./update.js";
 export interface SelfHostInitArguments {
     manifestPath: string;
     outputPath: string;
     install: boolean;
 }
-export declare function runSelfHostCommand(arguments_: readonly string[]): Promise<GeneratedSelfHostProject>;
+export declare function runSelfHostCommand(arguments_: readonly string[]): Promise<GeneratedSelfHostProject | SelfHostUpdatePlan>;
+export interface SelfHostUpdateArguments {
+    projectPath: string;
+    check: boolean;
+    confirm: boolean;
+}
+export declare function parseSelfHostUpdateArguments(arguments_: readonly string[]): SelfHostUpdateArguments;
 export declare function parseSelfHostInitArguments(arguments_: readonly string[]): SelfHostInitArguments;
 //# sourceMappingURL=command.d.ts.map

package/dist/self-host/command.js

@@ -2,11 +2,21 @@ import { readFile, stat } from "node:fs/promises";
 import { resolve } from "node:path";
 import { loadBundledSelfHostCatalogue } from "./catalogue.js";
 import { generateSelfHostProject, } from "./project-generator.js";
+import { updateSelfHostProject } from "./update.js";
 const maximumManifestBytes = 16 * 1_024;
 export async function runSelfHostCommand(arguments_) {
     const [subcommand, ...rest] = arguments_;
+    if (subcommand === "update") {
+        const parsed = parseSelfHostUpdateArguments(rest);
+        const plan = await updateSelfHostProject({
+            projectDirectory: parsed.projectPath,
+            apply: parsed.confirm,
+        });
+        printUpdatePlan(plan);
+        return plan;
+    }
     if (subcommand !== "init") {
-        throw new Error("Usage: helyx self-host init --manifest <path> [--output <path>] [--install]");
+        throw new Error("Usage: helyx self-host <init|update>; run helyx help for details");
     }
     const parsed = parseSelfHostInitArguments(rest);
     const manifestPath = resolve(parsed.manifestPath);
@@ -33,6 +43,58 @@ export async function runSelfHostCommand(arguments_) {
     console.log(`Created Helyx Self-Hosted starter at ${generated.directory}`);
     return generated;
 }
+export function parseSelfHostUpdateArguments(arguments_) {
+    let projectPath = ".";
+    let projectConfigured = false;
+    let check = false;
+    let confirm = false;
+    for (let index = 0; index < arguments_.length; index += 1) {
+        const argument = arguments_[index];
+        if (argument === "--check") {
+            if (check)
+                throw new Error("--check may be specified only once");
+            check = true;
+            continue;
+        }
+        if (argument === "--confirm") {
+            if (confirm)
+                throw new Error("--confirm may be specified only once");
+            confirm = true;
+            continue;
+        }
+        if (argument === "--project") {
+            const value = arguments_[index + 1];
+            if (!value || value.startsWith("--")) {
+                throw new Error("--project requires a path");
+            }
+            if (projectConfigured) {
+                throw new Error("--project may be specified only once");
+            }
+            projectPath = value;
+            projectConfigured = true;
+            index += 1;
+            continue;
+        }
+        throw new Error(`Unknown self-host update option: ${argument ?? ""}`);
+    }
+    if (check === confirm) {
+        throw new Error("Choose exactly one update mode: --check for a read-only report or --confirm to apply");
+    }
+    return { projectPath, check, confirm };
+}
+function printUpdatePlan(plan) {
+    if (plan.upToDate) {
+        console.log(`Helyx is current with reviewed catalogue ${plan.catalogueVersion}.`);
+        return;
+    }
+    console.log(`Reviewed catalogue ${plan.catalogueVersion} changes:`);
+    for (const change of plan.changes) {
+        console.log(`  ${change.package}: ${change.currentVersion} -> ${change.targetVersion}`);
+    }
+    console.log(plan.changes.length === 1
+        ? "1 Helyx package requires an update."
+        : `${plan.changes.length} Helyx packages require an update.`);
+}
 export function parseSelfHostInitArguments(arguments_) {
     let manifestPath;
     let outputPath = "./helyx";

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

@@ -70,6 +70,8 @@ async function writeGeneratedFiles(targetDirectory, manifest, catalogue) {
             start: "helyx start",
             doctor: "helyx doctor",
             migrate: "helyx migrate",
+            "update:check": "helyx self-host update --check",
+            update: "helyx self-host update --confirm && npm ci",
         },
         dependencies,
     };
@@ -238,7 +240,7 @@ export const selfHostEnvironmentContract = {
         optional: true,
     },
     HELYX_BOT_CONTROL_PORT: { value: "3001", optional: true },
-    HELYX_CLOUD_CONNECT_ENABLED: { value: "false", optional: false },
+    HELYX_CLOUD_CONNECT_ENABLED: { value: "true", optional: false },
     HELYX_CLOUD_ENROLMENT_TOKEN: {
         value: "replace-with-a-short-lived-enrolment-code",
         optional: true,

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

@@ -0,0 +1,26 @@
+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";
+}
+export interface SelfHostUpdatePlan {
+    projectDirectory: string;
+    catalogueVersion: number;
+    changes: SelfHostUpdateChange[];
+    upToDate: boolean;
+}
+export type SelfHostUpdateCommandRunner = (arguments_: readonly string[], workingDirectory: string) => Promise<void>;
+export interface SelfHostUpdateOptions {
+    projectDirectory?: string;
+    apply?: boolean;
+    catalogue?: SelfHostCatalogue;
+    catalogueLoader?: () => Promise<SelfHostCatalogue>;
+    commandRunner?: SelfHostUpdateCommandRunner;
+    now?: () => Date;
+}
+export declare function updateSelfHostProject(options?: SelfHostUpdateOptions): Promise<SelfHostUpdatePlan>;
+export declare function loadCurrentSelfHostCatalogue(fetcher?: typeof fetch): Promise<SelfHostCatalogue>;
+//# sourceMappingURL=update.d.ts.map

package/dist/self-host/update.js

@@ -0,0 +1,305 @@
+import semver from "semver";
+import { createHash } from "node:crypto";
+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";
+export const DEFAULT_SELF_HOST_CATALOGUE_URL = "https://api.helyx.gg/self-host/catalogue";
+const packageName = z.string().regex(/^@helyx\/[a-z0-9][a-z0-9-]*$/u);
+const modulePackage = z.string().regex(/^@helyx\/module-[a-z0-9][a-z0-9-]*$/u);
+const exactVersion = z
+    .string()
+    .refine((value) => semver.valid(value) === value, "must be exact semver");
+const packageJsonSchema = z
+    .object({
+    name: z.literal("helyx-self-hosted"),
+    private: z.literal(true),
+    dependencies: z.record(z.string(), z.string()),
+    scripts: z.record(z.string(), z.string()).optional(),
+})
+    .passthrough();
+const moduleSelectionSchema = z
+    .object({
+    schemaVersion: z.literal(1),
+    packages: z.array(modulePackage).max(30),
+})
+    .strict()
+    .superRefine((value, context) => {
+    if (new Set(value.packages).size !== value.packages.length) {
+        context.addIssue({
+            code: "custom",
+            path: ["packages"],
+            message: "module package names must be unique",
+        });
+    }
+});
+const managedFiles = [
+    ".gitignore",
+    "package.json",
+    "package-lock.json",
+    "helyx.modules.json",
+    "SHA256SUMS",
+];
+export async function updateSelfHostProject(options = {}) {
+    const projectDirectory = resolve(options.projectDirectory ?? ".");
+    assertSafeProjectDirectory(projectDirectory);
+    const [packageJson, selection, catalogue] = await Promise.all([
+        readProjectJson(projectDirectory),
+        readModuleSelection(projectDirectory),
+        options.catalogue
+            ? Promise.resolve(options.catalogue)
+            : (options.catalogueLoader ?? loadCurrentSelfHostCatalogue)(),
+    ]);
+    const targetDependencies = targetHelyxDependencies(catalogue, selection);
+    validateManagedDependencies(packageJson.dependencies, targetDependencies);
+    const changes = collectChanges(packageJson.dependencies, targetDependencies);
+    const plan = {
+        projectDirectory,
+        catalogueVersion: catalogue.catalogueVersion,
+        changes,
+        upToDate: changes.length === 0,
+    };
+    if (!options.apply || plan.upToDate)
+        return plan;
+    const backupDirectory = await createBackup(projectDirectory, options.now?.() ?? new Date());
+    try {
+        await ensureBackupIgnored(projectDirectory);
+        const nextPackageJson = {
+            ...packageJson,
+            scripts: {
+                ...packageJson.scripts,
+                "update:check": "helyx self-host update --check",
+                update: "helyx self-host update --confirm && npm ci",
+            },
+            dependencies: {
+                ...packageJson.dependencies,
+                ...Object.fromEntries(targetDependencies),
+            },
+        };
+        await atomicWriteJson(resolve(projectDirectory, "package.json"), nextPackageJson);
+        const runner = options.commandRunner ?? runNpmCommand;
+        await runner([
+            "install",
+            "--package-lock-only",
+            "--ignore-scripts",
+            "--no-audit",
+            "--no-fund",
+        ], projectDirectory);
+        await validateUpdatedLockfile(projectDirectory, targetDependencies);
+        await writeChecksums(projectDirectory);
+        return plan;
+    }
+    catch (error) {
+        await restoreBackup(projectDirectory, backupDirectory);
+        throw new Error("The self-host update failed and the managed project files were restored", { cause: error });
+    }
+}
+export async function loadCurrentSelfHostCatalogue(fetcher = fetch) {
+    let response;
+    try {
+        response = await fetcher(DEFAULT_SELF_HOST_CATALOGUE_URL, {
+            headers: { Accept: "application/json" },
+            signal: AbortSignal.timeout(15_000),
+        });
+    }
+    catch (error) {
+        throw new Error("The reviewed Helyx update catalogue is unavailable", {
+            cause: error,
+        });
+    }
+    if (!response.ok) {
+        throw new Error(`The reviewed Helyx update catalogue returned HTTP ${response.status}`);
+    }
+    const declaredLength = Number(response.headers.get("content-length") ?? "0");
+    if (declaredLength > 512 * 1_024) {
+        throw new Error("The reviewed Helyx update catalogue was too large");
+    }
+    const text = await response.text();
+    if (Buffer.byteLength(text, "utf8") > 512 * 1_024) {
+        throw new Error("The reviewed Helyx update catalogue was too large");
+    }
+    try {
+        return parseSelfHostCatalogue(JSON.parse(text));
+    }
+    catch (error) {
+        throw new Error("The reviewed Helyx update catalogue was invalid", {
+            cause: error,
+        });
+    }
+}
+function targetHelyxDependencies(catalogue, selection) {
+    if (catalogue.core.availability !== "published" ||
+        catalogue.generator.availability !== "published") {
+        throw new Error("The reviewed Helyx core release is not available");
+    }
+    const modulesByPackage = new Map(catalogue.modules.map((module) => [module.package, module]));
+    const selected = selection.packages.map((selectedPackage) => {
+        const module = modulesByPackage.get(selectedPackage);
+        if (!module ||
+            module.availability !== "published" ||
+            module.releaseStatus !== "live" ||
+            module.tier === "premium" ||
+            module.version === null) {
+            throw new Error(`Selected module is not in the current reviewed free live release: ${selectedPackage}`);
+        }
+        return [module.package, module.version];
+    });
+    return new Map([
+        [catalogue.core.package, catalogue.core.version],
+        [catalogue.generator.package, catalogue.generator.version],
+        ...selected,
+    ]);
+}
+function validateManagedDependencies(current, target) {
+    for (const [name, version] of Object.entries(current)) {
+        if (!name.startsWith("@helyx/"))
+            continue;
+        packageName.parse(name);
+        exactVersion.parse(version);
+        if (!target.has(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)) {
+            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",
+    }))
+        .sort((left, right) => left.package.localeCompare(right.package, "en"));
+}
+async function readProjectJson(projectDirectory) {
+    const value = JSON.parse(await readFile(resolve(projectDirectory, "package.json"), "utf8"));
+    return packageJsonSchema.parse(value);
+}
+async function readModuleSelection(projectDirectory) {
+    const value = JSON.parse(await readFile(resolve(projectDirectory, "helyx.modules.json"), "utf8"));
+    return moduleSelectionSchema.parse(value);
+}
+async function createBackup(projectDirectory, now) {
+    const timestamp = now.toISOString().replaceAll(":", "-");
+    const backupDirectory = resolve(projectDirectory, ".helyx", "backups", timestamp);
+    await mkdir(resolve(projectDirectory, ".helyx", "backups"), {
+        recursive: true,
+    });
+    await mkdir(backupDirectory);
+    for (const fileName of managedFiles) {
+        await copyFile(resolve(projectDirectory, fileName), resolve(backupDirectory, fileName));
+    }
+    return backupDirectory;
+}
+async function ensureBackupIgnored(projectDirectory) {
+    const path = resolve(projectDirectory, ".gitignore");
+    const current = await readFile(path, "utf8");
+    const lines = current
+        .replaceAll("\r\n", "\n")
+        .replaceAll("\r", "\n")
+        .split("\n");
+    if (lines.some((line) => line.trim() === ".helyx/"))
+        return;
+    await atomicWriteText(path, `${current.trimEnd()}\n.helyx/\n`);
+}
+async function restoreBackup(projectDirectory, backupDirectory) {
+    for (const fileName of managedFiles) {
+        await copyFile(resolve(backupDirectory, fileName), resolve(projectDirectory, fileName));
+    }
+}
+async function atomicWriteJson(path, value) {
+    const temporaryPath = `${path}.helyx-update`;
+    await writeFile(temporaryPath, formatJson(value), "utf8");
+    await rename(temporaryPath, path);
+}
+async function validateUpdatedLockfile(projectDirectory, target) {
+    const value = JSON.parse(await readFile(resolve(projectDirectory, "package-lock.json"), "utf8"));
+    if (!isRecord(value) || !isRecord(value.packages)) {
+        throw new Error("Updated package-lock.json is invalid");
+    }
+    const root = value.packages[""];
+    if (!isRecord(root) || !isRecord(root.dependencies)) {
+        throw new Error("Updated package-lock.json has no root dependencies");
+    }
+    for (const [name, version] of target) {
+        if (root.dependencies[name] !== version) {
+            throw new Error(`Updated package-lock.json does not pin ${name}@${version}`);
+        }
+    }
+}
+async function writeChecksums(projectDirectory) {
+    const fileNames = (await readdir(projectDirectory))
+        .filter((fileName) => fileName !== "SHA256SUMS")
+        .sort((left, right) => left.localeCompare(right, "en"));
+    const lines = [];
+    for (const fileName of fileNames) {
+        const file = await stat(resolve(projectDirectory, fileName));
+        if (!file.isFile())
+            continue;
+        const digest = createHash("sha256")
+            .update(await readFile(resolve(projectDirectory, fileName)))
+            .digest("hex");
+        lines.push(`${digest}  ${fileName}`);
+    }
+    await atomicWriteText(resolve(projectDirectory, "SHA256SUMS"), `${lines.join("\n")}\n`);
+}
+async function atomicWriteText(path, value) {
+    const temporaryPath = `${path}.helyx-update`;
+    await writeFile(temporaryPath, normalizeCrLf(value), "utf8");
+    await rename(temporaryPath, path);
+}
+function formatJson(value) {
+    return normalizeCrLf(`${JSON.stringify(value, null, 2)}\n`);
+}
+function normalizeCrLf(value) {
+    return value
+        .replaceAll("\r\n", "\n")
+        .replaceAll("\r", "\n")
+        .replaceAll("\n", "\r\n");
+}
+function assertSafeProjectDirectory(projectDirectory) {
+    if (projectDirectory === parse(projectDirectory).root) {
+        throw new Error("Refusing to update a filesystem root");
+    }
+}
+async function runNpmCommand(arguments_, workingDirectory) {
+    const npmCli = process.env.npm_execpath;
+    const executable = npmCli ? process.execPath : "npm";
+    const commandArguments = npmCli ? [npmCli, ...arguments_] : [...arguments_];
+    await new Promise((resolvePromise, reject) => {
+        const child = spawn(executable, commandArguments, {
+            cwd: workingDirectory,
+            env: { ...process.env, npm_config_ignore_scripts: "true" },
+            shell: process.platform === "win32" && npmCli === undefined,
+            stdio: "inherit",
+        });
+        const timeout = setTimeout(() => {
+            child.kill("SIGTERM");
+            reject(new Error("npm command exceeded the two-minute update limit"));
+        }, 120_000);
+        child.once("error", (error) => {
+            clearTimeout(timeout);
+            reject(error);
+        });
+        child.once("close", (code) => {
+            clearTimeout(timeout);
+            if (code === 0)
+                resolvePromise();
+            else
+                reject(new Error(`npm command failed with exit code ${String(code)}`));
+        });
+    });
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+//# sourceMappingURL=update.js.map

package/dist/setup.d.ts

@@ -1,9 +1,11 @@
 export interface SetupSelfHostEnvironmentOptions {
     cwd?: string;
     detectDockerCompose?: () => Promise<boolean>;
+    createDataEncryptionKey?: () => string;
 }
 export interface SetupSelfHostEnvironmentResult {
     created: boolean;
+    dataEncryptionKeyCreated: boolean;
     dockerComposeAvailable: boolean;
     environmentPath: string;
 }

package/dist/setup.js

@@ -1,9 +1,12 @@
+import { randomBytes } from "node:crypto";
 import { constants } from "node:fs";
-import { chmod, copyFile, readFile } from "node:fs/promises";
+import { chmod, copyFile, readFile, writeFile } from "node:fs/promises";
 import { resolve } from "node:path";
 import { spawn } from "node:child_process";
 import { parseEnv } from "node:util";
 const starterPackageName = "helyx-self-hosted";
+const dataEncryptionKeyName = "HELYX_DATA_ENCRYPTION_KEY";
+const dataEncryptionKeyPlaceholder = "replace-with-a-base64-encoded-32-byte-key";
 export async function setupSelfHostEnvironment(options = {}) {
     const cwd = resolve(options.cwd ?? process.cwd());
     await assertGeneratedStarter(cwd);
@@ -19,12 +22,51 @@ export async function setupSelfHostEnvironment(options = {}) {
         if (!isFileSystemError(error, "EEXIST"))
             throw error;
     }
+    const dataEncryptionKeyCreated = await ensureDataEncryptionKey(environmentPath, options.createDataEncryptionKey ?? createDataEncryptionKey);
     return {
         created,
+        dataEncryptionKeyCreated,
         dockerComposeAvailable: await (options.detectDockerCompose ?? detectDockerCompose)(),
         environmentPath,
     };
 }
+async function ensureDataEncryptionKey(environmentPath, createKey) {
+    const content = await readFile(environmentPath, "utf8");
+    const activeKeyPattern = new RegExp(`^[\\t ]*${dataEncryptionKeyName}[\\t ]*=[\\t ]*([^\\r\\n]*?)[\\t ]*(?=\\r?$)`, "mu");
+    const activeKey = activeKeyPattern.exec(content);
+    if (activeKey &&
+        activeKey[1] !== undefined &&
+        activeKey[1] !== "" &&
+        activeKey[1] !== dataEncryptionKeyPlaceholder) {
+        await chmod(environmentPath, 0o600);
+        return false;
+    }
+    const key = createKey();
+    const replacement = `${dataEncryptionKeyName}=${key}`;
+    let updated;
+    if (activeKey) {
+        updated = content.replace(activeKeyPattern, replacement);
+    }
+    else {
+        const commentedKeyPattern = new RegExp(`^[\\t ]*#[\\t ]*${dataEncryptionKeyName}[\\t ]*=[^\\r\\n]*(?=\\r?$)`, "mu");
+        if (commentedKeyPattern.test(content)) {
+            updated = content.replace(commentedKeyPattern, replacement);
+        }
+        else {
+            const newline = content.includes("\r\n") ? "\r\n" : "\n";
+            updated = `${content.trimEnd()}${newline}${replacement}${newline}`;
+        }
+    }
+    await writeFile(environmentPath, updated, {
+        encoding: "utf8",
+        mode: 0o600,
+    });
+    await chmod(environmentPath, 0o600);
+    return true;
+}
+function createDataEncryptionKey() {
+    return randomBytes(32).toString("base64");
+}
 export async function loadLocalEnvironment(cwd = process.cwd(), environment = process.env) {
     let content;
     try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@helyx/cli",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "description": "Command-line tools for running and generating self-hosted Helyx deployments.",
   "keywords": [
     "helyx",
@@ -52,9 +52,9 @@
     "build": "tsc -b"
   },
   "dependencies": {
-    "@helyx/bot": "0.2.1",
+    "@helyx/bot": "0.2.2",
     "@helyx/config": "0.2.1",
-    "@helyx/database": "0.2.0",
+    "@helyx/database": "0.2.1",
     "semver": "7.8.5",
     "zod": "4.4.3"
   },

package/self-host-catalogue.json

@@ -1,14 +1,14 @@
 {
   "schemaVersion": 1,
-  "catalogueVersion": 10,
+  "catalogueVersion": 11,
   "core": {
     "package": "@helyx/bot",
-    "version": "0.2.1",
+    "version": "0.2.2",
     "availability": "published"
   },
   "generator": {
     "package": "@helyx/cli",
-    "version": "0.2.2",
+    "version": "0.3.0",
     "command": "helyx",
     "availability": "published"
   },

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

@@ -1,41 +1,61 @@
-# Required Discord configuration.
+# REQUIRED — EDIT THESE VALUES
+
+# Discord
 DISCORD_TOKEN=replace-me
 DISCORD_CLIENT_ID=12345678901234567
 
-# Database defaults for the included Docker Compose service.
-# For direct Node.js or managed hosting, replace DATABASE_URL with the
-# connection string for your local or hosted PostgreSQL database.
+# Database
+# Docker: keep the URL. Direct Node.js/managed hosting: use your provider URL.
 DATABASE_URL=postgresql://database:5432/helyx
 DATABASE_SSL=disable
+
+# Included Docker database — both password values must match.
 PGUSER=helyx
 PGPASSWORD=replace-with-a-strong-password
+POSTGRES_DB=helyx
+POSTGRES_USER=helyx
+POSTGRES_PASSWORD=replace-with-a-strong-password
 
-# Generated module selection. Keep this file under version control.
-HELYX_MODULE_CATALOGUE_PATH=./helyx.modules.json
+# OPTIONAL EVERYDAY SETTINGS
 
-# Optional explicit additions must still be official reviewed packages.
-# HELYX_MODULE_PACKAGES=
+# Ready for dashboard linking, but remains unpaired until you use a one-use code.
+HELYX_CLOUD_CONNECT_ENABLED=true
+# HELYX_OWNER_USER_IDS=12345678901234567
+
+# trace, debug, info, warn, error, fatal or silent
+LOG_LEVEL=info
+
+# Guild-scoped development commands only
 # DISCORD_INTERNAL_GUILD_ID=12345678901234567
 
-# Optional private dashboard control endpoint. Configure both values together.
+# ADVANCED INTEGRATIONS — EDIT ONLY WHEN NEEDED
+
+# Additional reviewed module packages
+# HELYX_MODULE_PACKAGES=
+
+# Private dashboard control endpoint — configure both together
 # HELYX_BOT_CONTROL_SECRET=replace-with-a-base64-encoded-32-byte-key
 # HELYX_BOT_CONTROL_PORT=3001
 
-# Optional Helyx Cloud Connect. It remains fully disabled unless set to true.
-HELYX_CLOUD_CONNECT_ENABLED=false
+# Alternative Cloud Connect enrolment — the Discord command is preferred
 # HELYX_CLOUD_ENROLMENT_TOKEN=replace-with-a-short-lived-enrolment-code
 # HELYX_CLOUD_ENROLMENT_FILE=./helyx.cloud-enrolment.json
+
+# DANGER ZONE — HELYX-MANAGED VALUES, DO NOT EDIT
+
+# Generated module selection
+HELYX_MODULE_CATALOGUE_PATH=./helyx.modules.json
+
+# Generated privately by npm run setup. Never change it after Cloud Connect.
 # HELYX_DATA_ENCRYPTION_KEY=replace-with-a-base64-encoded-32-byte-key
+
+# Official Cloud Connect endpoints
 # HELYX_CLOUD_API_URL=https://api.helyx.gg
 # HELYX_CLOUD_ENDPOINT=wss://connect.helyx.gg/v1/connect
-# HELYX_OWNER_USER_IDS=12345678901234567
+
+# Security audit retention
 # HELYX_CLOUD_AUDIT_RETENTION_DAYS=90
 # HELYX_CLOUD_CREDENTIAL_AUDIT_RETENTION_DAYS=365
 
-LOG_LEVEL=info
+# Runtime mode
 NODE_ENV=production
-
-# Used only by the included Docker Compose PostgreSQL service.
-POSTGRES_DB=helyx
-POSTGRES_USER=helyx
-POSTGRES_PASSWORD=replace-with-a-strong-password

package/templates/self-host/README.md

@@ -1,6 +1,6 @@
 # Helyx Self-Hosted starter
 
-This private starter was generated from the reviewed Helyx self-host catalogue. It contains deployment configuration and exact npm dependencies, not Helyx source code or credentials.
+This self-host starter was generated from the reviewed Helyx catalogue. It contains deployment configuration and exact npm dependencies, not Helyx source code or credentials.
 
 ## Selected modules
 
@@ -22,7 +22,7 @@ Package installation and module activation are separate. Installed feature modul
 Use this path on a local machine or VPS without Docker. It requires Node.js `>=24 <27`, npm `>=11`, and a local or hosted PostgreSQL database. Helyx does not require Docker, but PostgreSQL remains mandatory.
 
 1. Run `npm ci`.
-2. Run `npm run setup`. Helyx creates `.env` from the supplied example without overwriting an existing file.
+2. Run `npm run setup`. Helyx creates `.env` from the supplied example and generates its private local data-encryption key. Repeating setup never replaces an existing key or configuration value.
 3. Edit `.env`, replace every placeholder and set `DATABASE_URL` for your PostgreSQL server.
 4. Set `DATABASE_SSL=disable` for a trusted local connection, or `require`/`verify-full` according to your database provider.
 5. Run `npm run doctor`.
@@ -32,7 +32,7 @@ Use this path on a local machine or VPS without Docker. It requires Node.js `>=2
 
 Use this path when Docker with Compose support is available. The included configuration runs both Helyx and PostgreSQL 17.
 
-1. Run `npm ci`, then `npm run setup`. This creates the local configuration safely; the bot itself will still run in Docker.
+1. Run `npm ci`, then `npm run setup`. This creates the local configuration and data-encryption key safely; the bot itself will still run in Docker.
 2. Edit `.env` and replace all placeholder credentials and passwords.
 3. Keep the supplied internal `DATABASE_URL` and `DATABASE_SSL=disable`.
 4. Run `docker compose up --build -d`.
@@ -41,7 +41,7 @@ Use this path when Docker with Compose support is available. The included config
 
 ### Managed bot hosting
 
-Use this path when a provider installs npm packages and runs the package start script for you. Configure `npm start` as the start command and supply every required variable through the provider's environment or variables panel. Use a PostgreSQL database reachable from that provider. A local `.env` file is not required when the host supplies the variables.
+Use this path when a provider installs npm packages and runs the package start script for you. Configure `npm start` as the start command and supply every required variable through the provider's environment or variables panel. Use a PostgreSQL database reachable from that provider. A local `.env` file is not required when the host supplies the variables. Generate `HELYX_DATA_ENCRYPTION_KEY` once with `node -e "console.log(require('node:crypto').randomBytes(32).toString('base64'))"`, store it in the provider's secret-variable panel and retain it across every restart and deployment.
 
 If a provider cannot run `npm ci`, execute `npm start`, or connect to PostgreSQL, it cannot run this Helyx starter. A future hosting-specific download may package additional provider files, but it cannot remove the PostgreSQL requirement.
 
@@ -57,12 +57,17 @@ If a provider cannot run `npm ci`, execute `npm start`, or connect to PostgreSQL
 
 Command registration is global or guild-scoped according to each reviewed command contribution. Discord may take time to refresh global commands. Installing a package does not enable its feature for a server; run `/helyx` in the server after startup to enable modules and configure their settings. Use `/permissions` when module or command access policies need to be changed.
 
+Generated self-host configuration enables the Cloud Connect connector by default, but it remains unpaired and shares nothing with the hosted dashboard until a deployment owner enters a one-use code with `/helyx-cloud connect`. Set `HELYX_CLOUD_CONNECT_ENABLED=false` if this deployment will remain entirely local.
+
 ## Backups and upgrades
 
 - Back up PostgreSQL and the complete project directory before an upgrade.
 - Retain `package-lock.json`; use `npm ci` for repeatable installation.
 - Do not edit dependency versions or `helyx.modules.json` independently.
-- Review Helyx release notes before changing exact dependency versions. There is no automatic updater in the first self-host release.
+- Run `npm run update:check` to compare the complete installed Helyx release set with the current reviewed catalogue.
+- Review the release notes, stop the bot, back up PostgreSQL, then run `npm run update`. Helyx backs up its managed project files, refreshes all exact Helyx versions and the lockfile together, and runs a clean install.
+- Run `npm run doctor` before restarting with `npm start`.
+- Existing starters that do not yet contain these scripts can use `npx --yes @helyx/cli@latest self-host update --check`, followed by the same command with `--confirm`, then `npm ci`.
 - Removing a package does not automatically delete retained module configuration or data.
 - Roll back application files and restore a compatible database backup if an upgrade cannot be completed safely.
 

package/templates/self-host/gitignore.template

@@ -1,4 +1,5 @@
 .env
+.helyx/
 helyx.cloud-enrolment.json
 node_modules/
 npm-debug.log*