@helyx/cli 0.1.1 → 0.1.3

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.1.3 - 2026-07-23
+
+- Add safe first-run environment setup, local `.env` loading and clearer Node.js, Docker Compose and managed-host guidance.
+
+## 0.1.2 - 2026-07-23
+
+- Identify the included Helyx Source Available Licence as `HSAL 1.0` and align public core dependencies.
+
 ## 0.1.1 - 2026-07-23
 
 - Run npm through its JavaScript entry point when available so starter generation works reliably on supported Windows and Node.js versions.

package/README.md

@@ -3,13 +3,14 @@
 The supported Helyx command-line entry point for running and generating self-hosted deployments.
 
 ```text
+helyx setup
 helyx start
 helyx migrate
 helyx doctor
 helyx self-host init --manifest ./helyx-build.json --output ./helyx
 ```
 
-`start` 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.
+`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.
 

package/dist/cli.js

@@ -2,18 +2,26 @@
 import { loadConfiguredModulePackages, resolveModulePackageSpecifiers, startBot, } from "@helyx/bot";
 import { parseBotEnvironment, parseDatabaseEnvironment } from "@helyx/config";
 import { checkDatabaseConnection, createDatabasePool, inspectCoreMigrations, runCoreMigrations, } from "@helyx/database";
+import { formatCommandError } from "./errors.js";
 import { runSelfHostCommand } from "./self-host/command.js";
+import { loadLocalEnvironment, setupSelfHostEnvironment } from "./setup.js";
 const command = process.argv[2];
 try {
     if (command === "start") {
+        await loadLocalEnvironment();
         await startBot();
     }
     else if (command === "migrate") {
+        await loadLocalEnvironment();
         await migrate();
     }
     else if (command === "doctor") {
+        await loadLocalEnvironment();
         await doctor();
     }
+    else if (command === "setup") {
+        await setup();
+    }
     else if (command === "self-host") {
         await runSelfHostCommand(process.argv.slice(3));
     }
@@ -28,10 +36,23 @@ try {
     }
 }
 catch (error) {
-    const value = error instanceof Error ? error : new Error(String(error));
-    console.error(`Helyx ${command ?? "command"} failed: ${value.message}`);
+    console.error(`Helyx ${command ?? "command"} failed: ${formatCommandError(error)}`);
     process.exitCode = 1;
 }
+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.");
+    if (result.dockerComposeAvailable) {
+        console.log("Docker Compose is available. You may use the included bot and PostgreSQL services.");
+    }
+    else {
+        console.log("Docker Compose was not detected. Direct Node.js operation is supported, but you must provide a local or hosted PostgreSQL database.");
+    }
+    console.log("Next: edit .env, replace every placeholder, then run npm run doctor.");
+    console.log("Managed hosts may set the same variables in their control panel instead of using .env.");
+}
 async function migrate() {
     const environment = parseDatabaseEnvironment(process.env);
     const database = createDatabasePool({
@@ -60,12 +81,12 @@ async function doctor() {
     try {
         await checkDatabaseConnection(database);
         const migrations = await inspectCoreMigrations(database);
-        if (migrations.pending.length > 0) {
-            throw new Error(`${migrations.pending.length} core migration(s) are pending; run helyx migrate`);
-        }
         const moduleSpecifiers = await resolveModulePackageSpecifiers(environment.HELYX_MODULE_PACKAGES, undefined, undefined, environment.HELYX_MODULE_CATALOGUE_PATH);
         const modules = await loadConfiguredModulePackages(moduleSpecifiers);
         console.log(`Helyx doctor passed: PostgreSQL connected, ${migrations.verified.length} core migrations verified, ${modules.length} module packages validated.`);
+        if (migrations.pending.length > 0) {
+            console.log(`${migrations.pending.length} core migration(s) are pending and will be applied automatically by npm start.`);
+        }
     }
     finally {
         await database.end();
@@ -75,6 +96,7 @@ function printHelp() {
     console.log(`Usage: helyx <command>
 
 Commands:
+  setup    Create .env safely and explain the available hosting paths
   start    Start the Helyx Discord bot
   migrate  Apply core PostgreSQL migrations and exit
   doctor   Validate environment, database schema and module packages

package/dist/errors.d.ts

@@ -0,0 +1,2 @@
+export declare function formatCommandError(error: unknown): string;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.js

@@ -0,0 +1,14 @@
+import { ZodError } from "zod";
+export function formatCommandError(error) {
+    if (error instanceof ZodError) {
+        const fields = [
+            ...new Set(error.issues
+                .map((issue) => issue.path.join("."))
+                .filter((field) => field.length > 0)),
+        ];
+        const fieldList = fields.length > 0 ? ` (${fields.join(", ")})` : "";
+        return `configuration is incomplete or invalid${fieldList}. Run "npm run setup" in a downloaded starter, edit .env, then retry`;
+    }
+    return error instanceof Error ? error.message : String(error);
+}
+//# sourceMappingURL=errors.js.map

package/dist/index.d.ts

@@ -2,4 +2,5 @@ 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 "./setup.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -2,4 +2,5 @@ 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 "./setup.js";
 //# sourceMappingURL=index.js.map

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

@@ -5,6 +5,7 @@ import { dirname, parse, resolve } from "node:path";
 import { parseSelfHostBuildManifest, } from "./manifest.js";
 const generatedFileNames = [
     ".env.example",
+    ".gitignore",
     ".npmrc",
     "Dockerfile",
     "compose.yaml",
@@ -65,6 +66,7 @@ async function writeGeneratedFiles(targetDirectory, manifest, catalogue) {
         packageManager: "npm@11.18.0",
         engines: { node: ">=24 <27", npm: ">=11" },
         scripts: {
+            setup: "helyx setup",
             start: "helyx start",
             doctor: "helyx doctor",
             migrate: "helyx migrate",
@@ -100,7 +102,11 @@ function renderReadme(template, manifest, catalogue) {
     return normalizeCrLf(template.replace("{{SELECTED_MODULES}}", selected));
 }
 function templateUrl(fileName) {
-    const templateName = fileName === ".npmrc" ? "npmrc.template" : fileName;
+    const templateName = fileName === ".npmrc"
+        ? "npmrc.template"
+        : fileName === ".gitignore"
+            ? "gitignore.template"
+            : fileName;
     return new URL(`../../templates/self-host/${templateName}`, import.meta.url);
 }
 function formatJson(value) {

package/dist/setup.d.ts

@@ -0,0 +1,12 @@
+export interface SetupSelfHostEnvironmentOptions {
+    cwd?: string;
+    detectDockerCompose?: () => Promise<boolean>;
+}
+export interface SetupSelfHostEnvironmentResult {
+    created: boolean;
+    dockerComposeAvailable: boolean;
+    environmentPath: string;
+}
+export declare function setupSelfHostEnvironment(options?: SetupSelfHostEnvironmentOptions): Promise<SetupSelfHostEnvironmentResult>;
+export declare function loadLocalEnvironment(cwd?: string, environment?: NodeJS.ProcessEnv): Promise<boolean>;
+//# sourceMappingURL=setup.d.ts.map

package/dist/setup.js

@@ -0,0 +1,101 @@
+import { constants } from "node:fs";
+import { chmod, copyFile, readFile } 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";
+export async function setupSelfHostEnvironment(options = {}) {
+    const cwd = resolve(options.cwd ?? process.cwd());
+    await assertGeneratedStarter(cwd);
+    const examplePath = resolve(cwd, ".env.example");
+    const environmentPath = resolve(cwd, ".env");
+    let created = false;
+    try {
+        await copyFile(examplePath, environmentPath, constants.COPYFILE_EXCL);
+        await chmod(environmentPath, 0o600);
+        created = true;
+    }
+    catch (error) {
+        if (!isFileSystemError(error, "EEXIST"))
+            throw error;
+    }
+    return {
+        created,
+        dockerComposeAvailable: await (options.detectDockerCompose ?? detectDockerCompose)(),
+        environmentPath,
+    };
+}
+export async function loadLocalEnvironment(cwd = process.cwd(), environment = process.env) {
+    let content;
+    try {
+        content = await readFile(resolve(cwd, ".env"), "utf8");
+    }
+    catch (error) {
+        if (isFileSystemError(error, "ENOENT"))
+            return false;
+        throw error;
+    }
+    for (const [key, value] of Object.entries(parseEnv(content))) {
+        if (key !== "NODE_OPTIONS" && environment[key] === undefined) {
+            environment[key] = value;
+        }
+    }
+    return true;
+}
+async function assertGeneratedStarter(cwd) {
+    let packageJson;
+    try {
+        packageJson = JSON.parse(await readFile(resolve(cwd, "package.json"), "utf8"));
+    }
+    catch (error) {
+        if (isFileSystemError(error, "ENOENT")) {
+            throw new Error("Run this command from the downloaded Helyx starter directory", { cause: error });
+        }
+        throw error;
+    }
+    if (typeof packageJson !== "object" ||
+        packageJson === null ||
+        !("name" in packageJson) ||
+        packageJson.name !== starterPackageName) {
+        throw new Error("Run this command from the downloaded Helyx starter directory");
+    }
+    try {
+        await readFile(resolve(cwd, ".env.example"), "utf8");
+    }
+    catch (error) {
+        if (isFileSystemError(error, "ENOENT")) {
+            throw new Error("The starter is missing its .env.example file", {
+                cause: error,
+            });
+        }
+        throw error;
+    }
+}
+async function detectDockerCompose() {
+    return new Promise((resolvePromise) => {
+        const child = spawn("docker", ["compose", "version"], {
+            shell: false,
+            stdio: "ignore",
+            windowsHide: true,
+        });
+        const timeout = setTimeout(() => {
+            child.kill("SIGTERM");
+            resolvePromise(false);
+        }, 5_000);
+        child.once("error", () => {
+            clearTimeout(timeout);
+            resolvePromise(false);
+        });
+        child.once("close", (code) => {
+            clearTimeout(timeout);
+            resolvePromise(code === 0);
+        });
+    });
+}
+function isFileSystemError(error, code) {
+    return (error instanceof Error &&
+        "code" in error &&
+        typeof error.code === "string" &&
+        error.code === code);
+}
+//# sourceMappingURL=setup.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@helyx/cli",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Command-line tools for running and generating self-hosted Helyx deployments.",
   "keywords": [
     "helyx",
@@ -9,7 +9,7 @@
     "self-hosted"
   ],
   "private": false,
-  "license": "SEE LICENSE IN LICENSE",
+  "license": "HSAL 1.0",
   "homepage": "https://helyx.gg/",
   "bugs": {
     "url": "https://github.com/ZyC0R3/Helyx/issues"
@@ -52,9 +52,9 @@
     "build": "tsc -b"
   },
   "dependencies": {
-    "@helyx/bot": "0.1.1",
-    "@helyx/config": "0.1.1",
-    "@helyx/database": "0.1.0",
+    "@helyx/bot": "0.1.2",
+    "@helyx/config": "0.1.2",
+    "@helyx/database": "0.1.1",
     "semver": "7.8.5",
     "zod": "4.4.3"
   },

package/self-host-catalogue.json

@@ -1,14 +1,14 @@
 {
   "schemaVersion": 1,
-  "catalogueVersion": 5,
+  "catalogueVersion": 7,
   "core": {
     "package": "@helyx/bot",
-    "version": "0.1.1",
+    "version": "0.1.2",
     "availability": "published"
   },
   "generator": {
     "package": "@helyx/cli",
-    "version": "0.1.1",
+    "version": "0.1.3",
     "command": "helyx",
     "availability": "published"
   },
@@ -16,7 +16,7 @@
     {
       "id": "helyx.feedback",
       "package": "@helyx/module-feedback",
-      "version": "1.0.1",
+      "version": "1.0.2",
       "name": "Feedback",
       "description": "Collect structured member feedback in a channel you choose.",
       "category": "Community",
@@ -25,7 +25,7 @@
     {
       "id": "helyx.welcome",
       "package": "@helyx/module-welcome",
-      "version": "1.0.1",
+      "version": "1.0.2",
       "name": "Welcome",
       "description": "Greet new members and optionally give them a starting role.",
       "category": "Community",
@@ -34,7 +34,7 @@
     {
       "id": "helyx.suggestions",
       "package": "@helyx/module-suggestions",
-      "version": "1.0.1",
+      "version": "1.0.2",
       "name": "Suggestions",
       "description": "Collect community ideas with reaction or button voting.",
       "category": "Community",
@@ -214,7 +214,7 @@
     {
       "id": "helyx.logging",
       "package": "@helyx/module-logging",
-      "version": "1.0.1",
+      "version": "1.0.2",
       "name": "Logging",
       "description": "Post selected Helyx module activity to one server channel.",
       "category": "Insights",

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

@@ -1,10 +1,14 @@
-# Required Discord and database configuration.
+# Required Discord configuration.
+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_URL=postgresql://database:5432/helyx
 DATABASE_SSL=disable
 PGUSER=helyx
 PGPASSWORD=replace-with-a-strong-password
-DISCORD_TOKEN=replace-me
-DISCORD_CLIENT_ID=12345678901234567
 
 # Generated module selection. Keep this file under version control.
 HELYX_MODULE_CATALOGUE_PATH=./helyx.modules.json
@@ -20,7 +24,7 @@ HELYX_MODULE_CATALOGUE_PATH=./helyx.modules.json
 LOG_LEVEL=info
 NODE_ENV=production
 
-# Used only by the included Docker Compose database.
+# 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

@@ -10,33 +10,52 @@ Package installation and module activation are separate. Installed feature modul
 
 ## Requirements
 
-- Node.js `>=24 <27` and npm `>=11`, or Docker with Compose support
 - A Discord application and bot token
-- PostgreSQL 17 or another currently supported PostgreSQL release
+- One of the supported runtime paths below
+- PostgreSQL 17 or another currently supported PostgreSQL release, supplied by your chosen path
 - A safe backup location for the database and this project's lockfile
 
-## Local setup
+## Choose a runtime path
+
+### 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 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.
+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`.
+6. Run `npm start`.
+
+### Docker Compose
+
+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.
+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`.
+5. Review startup with `docker compose logs -f bot`.
+6. Stop services with `docker compose down`. Do not add `--volumes` unless you deliberately intend to delete the database volume.
+
+### 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.
+
+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.
+
+## Discord setup
 
 1. In the Discord Developer Portal, create or select an application and add its bot user.
-2. Copy the application ID into `DISCORD_CLIENT_ID`. Generate a bot token and copy it into `DISCORD_TOKEN`; never place that token in Discord, Git, screenshots or support messages.
+2. Copy the application ID into `DISCORD_CLIENT_ID`. Generate a bot token and place it directly in `.env` or the host's variables panel; never place that token in Discord, Git, screenshots or support messages.
 3. Install the bot using both the `bot` and `applications.commands` scopes. Review the permissions required by your selected modules and grant only what you intend; administrator access is convenient but not required by Helyx core.
-4. Copy `.env.example` to `.env` and replace every placeholder credential. Do not commit `.env`.
-5. For a non-Compose PostgreSQL server, replace `DATABASE_URL` and set `DATABASE_SSL=require` or `verify-full` as required by the provider. `PGUSER`, `PGPASSWORD` and `POSTGRES_*` are for the included Compose database only.
-6. Run `npm ci`.
-7. Run `npm run doctor` to validate the environment, database and selected packages without signing in to Discord or changing the database.
-8. Run `npm start`.
 
 `npm start` validates the environment, connects to PostgreSQL, applies core and selected-module migrations safely, validates installed modules, synchronises Discord commands and then reports readiness. Do not run a separate migration command before every start. `npm run migrate` is available when you deliberately need to apply core migrations without starting Discord.
 
-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.
-
-## Docker Compose
+`npm run doctor` validates the environment, PostgreSQL connection, existing migration history and selected packages without signing in to Discord or modifying the database. On a new database it reports migrations that `npm start` will apply automatically.
 
-1. Copy `.env.example` to `.env` and replace all placeholder credentials.
-2. Keep the included internal `DATABASE_URL` and `DATABASE_SSL=disable` only when using the Compose database service on its private network.
-3. Run `docker compose up --build -d`.
-4. Review startup with `docker compose logs -f bot`.
-5. Stop services with `docker compose down`. Do not add `--volumes` unless you deliberately intend to delete the database volume.
+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.
 
 ## Backups and upgrades
 

package/templates/self-host/gitignore.template

@@ -0,0 +1,3 @@
+.env
+node_modules/
+npm-debug.log*