@helyx/cli 0.1.0

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

@@ -0,0 +1,236 @@
+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 { parseSelfHostBuildManifest, } from "./manifest.js";
+const generatedFileNames = [
+    ".env.example",
+    ".npmrc",
+    "Dockerfile",
+    "compose.yaml",
+    "README.md",
+];
+export async function generateSelfHostProject(options) {
+    const manifest = parseSelfHostBuildManifest(options.manifest, options.catalogue);
+    const targetDirectory = resolve(options.targetDirectory);
+    assertSafeTargetDirectory(targetDirectory);
+    await mkdir(dirname(targetDirectory), { recursive: true });
+    let created = false;
+    try {
+        await mkdir(targetDirectory);
+        created = true;
+        await writeGeneratedFiles(targetDirectory, manifest, options.catalogue);
+        const runner = options.commandRunner ?? runNpmCommand;
+        await runner([
+            "install",
+            "--package-lock-only",
+            "--ignore-scripts",
+            "--no-audit",
+            "--no-fund",
+        ], targetDirectory);
+        await validateGeneratedLockfile(targetDirectory, manifest);
+        if (options.install) {
+            await runner(["ci", "--no-audit", "--no-fund"], targetDirectory);
+        }
+        await writeChecksums(targetDirectory);
+        const files = (await readdir(targetDirectory)).sort((left, right) => left.localeCompare(right, "en"));
+        return { directory: targetDirectory, manifest, files };
+    }
+    catch (error) {
+        if (created) {
+            await rm(targetDirectory, {
+                recursive: true,
+                force: true,
+                maxRetries: 5,
+                retryDelay: 100,
+            }).catch(() => undefined);
+        }
+        throw error;
+    }
+}
+async function writeGeneratedFiles(targetDirectory, manifest, catalogue) {
+    const dependencyEntries = [
+        [manifest.core.package, manifest.core.version],
+        [manifest.generator.package, manifest.generator.version],
+        ...manifest.modules.map((module) => [module.package, module.version]),
+    ];
+    dependencyEntries.sort(([left], [right]) => left.localeCompare(right, "en"));
+    const dependencies = Object.fromEntries(dependencyEntries);
+    const packageJson = {
+        name: "helyx-self-hosted",
+        version: "1.0.0",
+        private: true,
+        license: "UNLICENSED",
+        type: "module",
+        packageManager: "npm@11.18.0",
+        engines: { node: ">=24 <27", npm: ">=11" },
+        scripts: {
+            start: "helyx start",
+            doctor: "helyx doctor",
+            migrate: "helyx migrate",
+        },
+        dependencies,
+    };
+    const moduleCatalogue = {
+        schemaVersion: 1,
+        packages: manifest.modules.map((module) => module.package),
+    };
+    await writeFile(resolve(targetDirectory, "package.json"), formatJson(packageJson), "utf8");
+    await writeFile(resolve(targetDirectory, "helyx.modules.json"), formatJson(moduleCatalogue), "utf8");
+    for (const fileName of generatedFileNames) {
+        const template = await readFile(templateUrl(fileName), "utf8");
+        if (fileName === ".env.example")
+            validateEnvironmentTemplate(template);
+        const content = fileName === "README.md"
+            ? renderReadme(template, manifest, catalogue)
+            : normalizeCrLf(template);
+        await writeFile(resolve(targetDirectory, fileName), content, "utf8");
+    }
+}
+function renderReadme(template, manifest, catalogue) {
+    const modulesById = new Map(catalogue.modules.map((module) => [module.id, module]));
+    const selected = manifest.modules.length
+        ? manifest.modules
+            .map((module) => {
+            const definition = modulesById.get(module.id);
+            return `- ${definition?.name ?? module.id} (\`${module.package}@${module.version}\`)`;
+        })
+            .join("\n")
+        : "- No feature modules selected. This is a core-only installation.";
+    return normalizeCrLf(template.replace("{{SELECTED_MODULES}}", selected));
+}
+function templateUrl(fileName) {
+    const templateName = fileName === ".npmrc" ? "npmrc.template" : fileName;
+    return new URL(`../../templates/self-host/${templateName}`, import.meta.url);
+}
+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 validateEnvironmentTemplate(template) {
+    const lines = new Set(template
+        .replaceAll("\r\n", "\n")
+        .split("\n")
+        .map((line) => line.trim()));
+    for (const [key, definition] of Object.entries(selfHostEnvironmentContract)) {
+        const expected = `${definition.optional ? "# " : ""}${key}=${definition.value}`;
+        if (!lines.has(expected)) {
+            throw new Error(`Self-host environment template does not match the bot contract: ${key}`);
+        }
+    }
+}
+async function validateGeneratedLockfile(targetDirectory, manifest) {
+    const lockfilePath = resolve(targetDirectory, "package-lock.json");
+    const lockfile = JSON.parse(await readFile(lockfilePath, "utf8"));
+    if (!isRecord(lockfile) || !isRecord(lockfile.packages)) {
+        throw new Error("Generated package-lock.json is invalid");
+    }
+    const root = lockfile.packages[""];
+    if (!isRecord(root)) {
+        throw new Error("Generated package-lock.json has no root dependencies");
+    }
+    const lockedDependencies = root.dependencies;
+    if (!isRecord(lockedDependencies)) {
+        throw new Error("Generated package-lock.json has no root dependencies");
+    }
+    const expected = new Map([
+        [manifest.core.package, manifest.core.version],
+        [manifest.generator.package, manifest.generator.version],
+        ...manifest.modules.map((module) => [module.package, module.version]),
+    ]);
+    if (Object.keys(lockedDependencies).length !== expected.size ||
+        [...expected].some(([packageName, version]) => lockedDependencies[packageName] !== version)) {
+        throw new Error("Generated package-lock.json does not match the selected exact dependencies");
+    }
+}
+async function writeChecksums(targetDirectory) {
+    const fileNames = (await readdir(targetDirectory))
+        .filter((fileName) => fileName !== "SHA256SUMS")
+        .sort((left, right) => left.localeCompare(right, "en"));
+    const lines = [];
+    for (const fileName of fileNames) {
+        const file = await stat(resolve(targetDirectory, fileName));
+        if (!file.isFile())
+            continue;
+        const digest = createHash("sha256")
+            .update(await readFile(resolve(targetDirectory, fileName)))
+            .digest("hex");
+        lines.push(`${digest}  ${fileName}`);
+    }
+    await writeFile(resolve(targetDirectory, "SHA256SUMS"), normalizeCrLf(`${lines.join("\n")}\n`), "utf8");
+}
+function assertSafeTargetDirectory(targetDirectory) {
+    if (targetDirectory === parse(targetDirectory).root) {
+        throw new Error("Refusing to generate a self-host project at a filesystem root");
+    }
+}
+async function runNpmCommand(arguments_, workingDirectory) {
+    const executable = process.platform === "win32" ? "npm.cmd" : "npm";
+    await new Promise((resolvePromise, reject) => {
+        const child = spawn(executable, [...arguments_], {
+            cwd: workingDirectory,
+            env: arguments_.includes("--ignore-scripts")
+                ? { ...process.env, npm_config_ignore_scripts: "true" }
+                : process.env,
+            shell: false,
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        child.stdout.resume();
+        child.stderr.resume();
+        const timeout = setTimeout(() => {
+            child.kill("SIGTERM");
+            reject(new Error("npm command exceeded the two-minute generation 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)}; rerun it in the generated directory for detailed diagnostics`));
+        });
+    });
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+// This compile-time map intentionally stays adjacent to the generator. Adding a
+// bot environment field makes the generated contract fail to compile until the
+// self-host example receives an explicit safe value or omission decision.
+export const selfHostEnvironmentContract = {
+    DATABASE_URL: {
+        value: "postgresql://database:5432/helyx",
+        optional: false,
+    },
+    DATABASE_SSL: { value: "disable", optional: false },
+    DISCORD_TOKEN: { value: "replace-me", optional: false },
+    DISCORD_CLIENT_ID: { value: "12345678901234567", optional: false },
+    DISCORD_INTERNAL_GUILD_ID: {
+        value: "12345678901234567",
+        optional: true,
+    },
+    HELYX_MODULE_PACKAGES: {
+        value: "",
+        optional: true,
+    },
+    HELYX_MODULE_CATALOGUE_PATH: {
+        value: "./helyx.modules.json",
+        optional: false,
+    },
+    HELYX_BOT_CONTROL_SECRET: {
+        value: "replace-with-a-base64-encoded-32-byte-key",
+        optional: true,
+    },
+    HELYX_BOT_CONTROL_PORT: { value: "3001", optional: true },
+    LOG_LEVEL: { value: "info", optional: false },
+    NODE_ENV: { value: "production", optional: false },
+};
+//# sourceMappingURL=project-generator.js.map

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@helyx/cli",
+  "version": "0.1.0",
+  "description": "Command-line tools for running and generating self-hosted Helyx deployments.",
+  "keywords": [
+    "helyx",
+    "discord",
+    "cli",
+    "self-hosted"
+  ],
+  "private": false,
+  "license": "SEE LICENSE IN LICENSE",
+  "homepage": "https://helyx.gg/",
+  "bugs": {
+    "url": "https://github.com/ZyC0R3/Helyx/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ZyC0R3/Helyx.git",
+    "directory": "packages/cli"
+  },
+  "engines": {
+    "node": ">=24 <27",
+    "npm": ">=11"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "type": "module",
+  "files": [
+    "dist",
+    "!dist/*.tsbuildinfo",
+    "!dist/**/*.map",
+    "self-host-catalogue.json",
+    "templates",
+    "README.md",
+    "LICENSE"
+  ],
+  "bin": {
+    "helyx": "./dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./catalogue.json": "./self-host-catalogue.json"
+  },
+  "scripts": {
+    "build": "tsc -b"
+  },
+  "dependencies": {
+    "@helyx/bot": "0.1.0",
+    "@helyx/config": "0.1.0",
+    "@helyx/database": "0.1.0",
+    "semver": "7.8.5",
+    "zod": "4.4.3"
+  },
+  "devDependencies": {
+    "@types/semver": "7.7.1"
+  }
+}

package/self-host-catalogue.json

@@ -0,0 +1,278 @@
+{
+  "schemaVersion": 1,
+  "catalogueVersion": 3,
+  "core": {
+    "package": "@helyx/bot",
+    "version": "0.1.0",
+    "availability": "unpublished"
+  },
+  "generator": {
+    "package": "@helyx/cli",
+    "version": "0.1.0",
+    "command": "helyx",
+    "availability": "unpublished"
+  },
+  "modules": [
+    {
+      "id": "helyx.feedback",
+      "package": "@helyx/module-feedback",
+      "version": "1.0.1",
+      "name": "Feedback",
+      "description": "Collect structured member feedback in a channel you choose.",
+      "category": "Community",
+      "availability": "published"
+    },
+    {
+      "id": "helyx.welcome",
+      "package": "@helyx/module-welcome",
+      "version": "1.0.1",
+      "name": "Welcome",
+      "description": "Greet new members and optionally give them a starting role.",
+      "category": "Community",
+      "availability": "published"
+    },
+    {
+      "id": "helyx.suggestions",
+      "package": "@helyx/module-suggestions",
+      "version": "1.0.1",
+      "name": "Suggestions",
+      "description": "Collect community ideas with reaction or button voting.",
+      "category": "Community",
+      "availability": "published"
+    },
+    {
+      "id": "helyx.polls",
+      "package": "@helyx/module-polls",
+      "version": null,
+      "name": "Polls",
+      "description": "Run clear single or multiple-choice polls.",
+      "category": "Community",
+      "availability": "planned"
+    },
+    {
+      "id": "helyx.starboard",
+      "package": "@helyx/module-starboard",
+      "version": null,
+      "name": "Starboard",
+      "description": "Highlight messages your community values.",
+      "category": "Community",
+      "availability": "planned"
+    },
+    {
+      "id": "helyx.levels",
+      "package": "@helyx/module-levels",
+      "version": null,
+      "name": "Levels",
+      "description": "Optional participation levels and rewards.",
+      "category": "Community",
+      "availability": "planned"
+    },
+    {
+      "id": "helyx.moderation",
+      "package": "@helyx/module-moderation",
+      "version": null,
+      "name": "Moderation",
+      "description": "Warnings, timeouts, kicks and bans with audit context.",
+      "category": "Safety",
+      "availability": "planned"
+    },
+    {
+      "id": "helyx.automod",
+      "package": "@helyx/module-automod",
+      "version": null,
+      "name": "Auto moderation",
+      "description": "Apply transparent rules to spam and unsafe content.",
+      "category": "Safety",
+      "availability": "planned"
+    },
+    {
+      "id": "helyx.verification",
+      "package": "@helyx/module-verification",
+      "version": null,
+      "name": "Verification",
+      "description": "Add a deliberate member verification step.",
+      "category": "Safety",
+      "availability": "planned"
+    },
+    {
+      "id": "helyx.antiraid",
+      "package": "@helyx/module-antiraid",
+      "version": null,
+      "name": "Raid protection",
+      "description": "Detect and slow unusual join activity.",
+      "category": "Safety",
+      "availability": "planned"
+    },
+    {
+      "id": "helyx.tickets",
+      "package": "@helyx/module-tickets",
+      "version": null,
+      "name": "Tickets",
+      "description": "Private support requests with ownership and transcripts.",
+      "category": "Support",
+      "availability": "planned"
+    },
+    {
+      "id": "helyx.forms",
+      "package": "@helyx/module-forms",
+      "version": null,
+      "name": "Forms",
+      "description": "Collect structured requests through Discord modals.",
+      "category": "Support",
+      "availability": "planned"
+    },
+    {
+      "id": "helyx.faq",
+      "package": "@helyx/module-faq",
+      "version": null,
+      "name": "Knowledge base",
+      "description": "Answer common questions with maintained server guidance.",
+      "category": "Support",
+      "availability": "planned"
+    },
+    {
+      "id": "helyx.autoroles",
+      "package": "@helyx/module-autoroles",
+      "version": null,
+      "name": "Auto roles",
+      "description": "Assign appropriate roles when members join.",
+      "category": "Automation",
+      "availability": "planned"
+    },
+    {
+      "id": "helyx.reactionroles",
+      "package": "@helyx/module-reactionroles",
+      "version": null,
+      "name": "Self roles",
+      "description": "Let members select approved roles themselves.",
+      "category": "Automation",
+      "availability": "planned"
+    },
+    {
+      "id": "helyx.reminders",
+      "package": "@helyx/module-reminders",
+      "version": null,
+      "name": "Reminders",
+      "description": "Schedule personal and server reminders.",
+      "category": "Automation",
+      "availability": "planned"
+    },
+    {
+      "id": "helyx.tempvoice",
+      "package": "@helyx/module-tempvoice",
+      "version": null,
+      "name": "Temporary voice",
+      "description": "Create voice rooms that clean themselves up.",
+      "category": "Automation",
+      "availability": "planned"
+    },
+    {
+      "id": "helyx.scheduler",
+      "package": "@helyx/module-scheduler",
+      "version": null,
+      "name": "Scheduler",
+      "description": "Run approved messages and actions on a schedule.",
+      "category": "Automation",
+      "availability": "planned"
+    },
+    {
+      "id": "helyx.events",
+      "package": "@helyx/module-events",
+      "version": null,
+      "name": "Events",
+      "description": "Plan events and track attendance.",
+      "category": "Engagement",
+      "availability": "planned"
+    },
+    {
+      "id": "helyx.giveaways",
+      "package": "@helyx/module-giveaways",
+      "version": null,
+      "name": "Giveaways",
+      "description": "Run auditable giveaways with eligibility rules.",
+      "category": "Engagement",
+      "availability": "planned"
+    },
+    {
+      "id": "helyx.birthdays",
+      "package": "@helyx/module-birthdays",
+      "version": null,
+      "name": "Birthdays",
+      "description": "Celebrate opted-in member birthdays.",
+      "category": "Engagement",
+      "availability": "planned"
+    },
+    {
+      "id": "helyx.counting",
+      "package": "@helyx/module-counting",
+      "version": null,
+      "name": "Counting",
+      "description": "Run a configurable community counting channel.",
+      "category": "Engagement",
+      "availability": "planned"
+    },
+    {
+      "id": "helyx.logging",
+      "package": "@helyx/module-logging",
+      "version": "1.0.1",
+      "name": "Logging",
+      "description": "Post selected Helyx module activity to one server channel.",
+      "category": "Insights",
+      "availability": "published"
+    },
+    {
+      "id": "helyx.analytics",
+      "package": "@helyx/module-analytics",
+      "version": null,
+      "name": "Analytics",
+      "description": "Understand server activity with privacy-conscious summaries.",
+      "category": "Insights",
+      "availability": "planned"
+    },
+    {
+      "id": "helyx.health",
+      "package": "@helyx/module-health",
+      "version": null,
+      "name": "Server health",
+      "description": "Surface configuration problems and missing permissions.",
+      "category": "Insights",
+      "availability": "planned"
+    },
+    {
+      "id": "helyx.youtube",
+      "package": "@helyx/module-youtube",
+      "version": null,
+      "name": "YouTube alerts",
+      "description": "Post when selected channels publish or go live.",
+      "category": "Integrations",
+      "availability": "planned"
+    },
+    {
+      "id": "helyx.twitch",
+      "package": "@helyx/module-twitch",
+      "version": null,
+      "name": "Twitch alerts",
+      "description": "Announce selected live streams.",
+      "category": "Integrations",
+      "availability": "planned"
+    },
+    {
+      "id": "helyx.rss",
+      "package": "@helyx/module-rss",
+      "version": null,
+      "name": "RSS feeds",
+      "description": "Publish updates from selected feeds.",
+      "category": "Integrations",
+      "availability": "planned"
+    },
+    {
+      "id": "helyx.github",
+      "package": "@helyx/module-github",
+      "version": null,
+      "name": "GitHub updates",
+      "description": "Follow releases and repository activity.",
+      "category": "Integrations",
+      "availability": "planned"
+    }
+  ]
+}

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

@@ -0,0 +1,26 @@
+# Required Discord and database configuration.
+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
+
+# Optional explicit additions must still be official reviewed packages.
+# HELYX_MODULE_PACKAGES=
+# DISCORD_INTERNAL_GUILD_ID=12345678901234567
+
+# Optional private dashboard control endpoint. Configure both values together.
+# HELYX_BOT_CONTROL_SECRET=replace-with-a-base64-encoded-32-byte-key
+# HELYX_BOT_CONTROL_PORT=3001
+
+LOG_LEVEL=info
+NODE_ENV=production
+
+# Used only by the included Docker Compose database.
+POSTGRES_DB=helyx
+POSTGRES_USER=helyx
+POSTGRES_PASSWORD=replace-with-a-strong-password

package/templates/self-host/Dockerfile

@@ -0,0 +1,15 @@
+FROM node:24-bookworm-slim
+
+WORKDIR /app
+
+COPY package.json package-lock.json ./
+RUN npm ci --omit=dev
+
+COPY helyx.modules.json ./
+
+ENV HELYX_MODULE_CATALOGUE_PATH=/app/helyx.modules.json
+ENV NODE_ENV=production
+
+USER node
+
+CMD ["npm", "start"]

package/templates/self-host/README.md

@@ -0,0 +1,56 @@
+# 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.
+
+## Selected modules
+
+{{SELECTED_MODULES}}
+
+Package installation and module activation are separate. Installed feature modules start disabled for every Discord server. Enable and configure them only after the bot is running.
+
+## 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
+- A safe backup location for the database and this project's lockfile
+
+## Local 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.
+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
+
+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.
+
+## 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.
+- 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.
+
+## Adding or removing modules
+
+Use a newly generated manifest or the supported Helyx self-host command once module-change commands are released. A package being present does not enable it for a Discord server. Unknown packages, Git URLs, file paths and unreviewed registries are not supported.
+
+## Support and security
+
+Use the official Helyx support route for ordinary help. Report suspected vulnerabilities privately through the security contact published by Helyx; do not include bot tokens, database credentials or private server content in a report.