@helyx/cli 0.3.0 → 0.3.3

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## 0.3.3
+
+### Patch Changes
+
+- 0229cb1: Add the versioned Helyx privacy-provider contract, strict write and nullable
+  read boundaries, guarded attribution migrations, bounded hosted and self-hosted
+  provider execution, and the Privacy Centre runtime configuration.
+- Updated dependencies [0229cb1]
+  - @helyx/database@0.3.0
+  - @helyx/config@0.3.0
+  - @helyx/bot@0.3.0
+
+## 0.3.2
+
+### Patch Changes
+
+- Correct generated self-host catalogue metadata for modules that are not yet in development.
+- Updated dependencies
+  - @helyx/config@0.2.2
+  - @helyx/database@0.2.2
+  - @helyx/bot@0.2.3
+
+## 0.3.1
+
+### Patch Changes
+
+- 9e290e1: Load the current reviewed self-host catalogue from the fixed Helyx API endpoint when generating a downloaded starter project, allowing compatible module-only releases without republishing the CLI. Catalogue requests now reject redirects, non-JSON responses, oversized bodies, invalid schemas and unavailable or stale catalogue data.
+
 ## 0.3.0
 
 ### Minor Changes

package/README.md

@@ -14,7 +14,7 @@ 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 init` retrieves the current reviewed catalogue from the fixed Helyx API endpoint, validates a downloaded build manifest against it, creates a new starter-project directory, pins the runtime and selected official modules, generates a lockfile with lifecycle scripts disabled, and writes checksums. The request has strict timeout, response-size, JSON-schema and official-package checks; no arbitrary catalogue URL or stale bundled fallback is accepted. Add `--install` only when the dependencies should also be installed locally. Unknown, unpublished, duplicated, stale 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.
 

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

@@ -1,11 +1,16 @@
-import { type GeneratedSelfHostProject } from "./project-generator.js";
+import type { SelfHostCatalogue } from "./catalogue.js";
+import { generateSelfHostProject, 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 | SelfHostUpdatePlan>;
+export interface SelfHostCommandDependencies {
+    catalogueLoader?: () => Promise<SelfHostCatalogue>;
+    projectGenerator?: typeof generateSelfHostProject;
+}
+export declare function runSelfHostCommand(arguments_: readonly string[], dependencies?: SelfHostCommandDependencies): Promise<GeneratedSelfHostProject | SelfHostUpdatePlan>;
 export interface SelfHostUpdateArguments {
     projectPath: string;
     check: boolean;

package/dist/self-host/command.js

@@ -1,16 +1,18 @@
 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";
+import { loadCurrentSelfHostCatalogue, updateSelfHostProject, } from "./update.js";
 const maximumManifestBytes = 16 * 1_024;
-export async function runSelfHostCommand(arguments_) {
+export async function runSelfHostCommand(arguments_, dependencies = {}) {
     const [subcommand, ...rest] = arguments_;
     if (subcommand === "update") {
         const parsed = parseSelfHostUpdateArguments(rest);
         const plan = await updateSelfHostProject({
             projectDirectory: parsed.projectPath,
             apply: parsed.confirm,
+            ...(dependencies.catalogueLoader
+                ? { catalogueLoader: dependencies.catalogueLoader }
+                : {}),
         });
         printUpdatePlan(plan);
         return plan;
@@ -33,8 +35,8 @@ export async function runSelfHostCommand(arguments_) {
             cause: error,
         });
     }
-    const catalogue = await loadBundledSelfHostCatalogue();
-    const generated = await generateSelfHostProject({
+    const catalogue = await (dependencies.catalogueLoader ?? loadCurrentSelfHostCatalogue)();
+    const generated = await (dependencies.projectGenerator ?? generateSelfHostProject)({
         catalogue,
         manifest,
         targetDirectory: parsed.outputPath,

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

@@ -240,6 +240,15 @@ export const selfHostEnvironmentContract = {
         optional: true,
     },
     HELYX_BOT_CONTROL_PORT: { value: "3001", optional: true },
+    HELYX_PRIVACY_ENABLED: { value: "false", optional: false },
+    HELYX_PRIVACY_EXECUTOR_DATABASE_URL: {
+        value: "<dedicated-privacy-executor-postgresql-url>",
+        optional: true,
+    },
+    HELYX_PRIVACY_EXECUTOR_DATABASE_SSL: {
+        value: "disable",
+        optional: true,
+    },
     HELYX_CLOUD_CONNECT_ENABLED: { value: "true", optional: false },
     HELYX_CLOUD_ENROLMENT_TOKEN: {
         value: "replace-with-a-short-lived-enrolment-code",

package/dist/self-host/update.js

@@ -6,6 +6,8 @@ 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 maximumCatalogueBytes = 512 * 1_024;
+const catalogueTimeoutMilliseconds = 15_000;
 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
@@ -100,34 +102,74 @@ export async function loadCurrentSelfHostCatalogue(fetcher = fetch) {
     try {
         response = await fetcher(DEFAULT_SELF_HOST_CATALOGUE_URL, {
             headers: { Accept: "application/json" },
-            signal: AbortSignal.timeout(15_000),
+            redirect: "error",
+            signal: AbortSignal.timeout(catalogueTimeoutMilliseconds),
         });
     }
     catch (error) {
-        throw new Error("The reviewed Helyx update catalogue is unavailable", {
+        throw new Error("The reviewed Helyx self-host catalogue is unavailable", {
             cause: error,
         });
     }
     if (!response.ok) {
-        throw new Error(`The reviewed Helyx update catalogue returned HTTP ${response.status}`);
+        throw new Error(`The reviewed Helyx self-host 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 contentType = response.headers.get("content-type")?.toLowerCase();
+    if (!contentType?.startsWith("application/json")) {
+        throw new Error("The reviewed Helyx self-host catalogue did not return JSON");
     }
-    const text = await response.text();
-    if (Buffer.byteLength(text, "utf8") > 512 * 1_024) {
-        throw new Error("The reviewed Helyx update catalogue was too large");
+    const declaredLengthHeader = response.headers.get("content-length");
+    if (declaredLengthHeader !== null) {
+        const declaredLength = Number(declaredLengthHeader);
+        if (!Number.isSafeInteger(declaredLength) ||
+            declaredLength < 0 ||
+            declaredLength > maximumCatalogueBytes) {
+            throw new Error("The reviewed Helyx self-host catalogue had an invalid size");
+        }
     }
+    const text = await readBoundedCatalogueBody(response);
     try {
         return parseSelfHostCatalogue(JSON.parse(text));
     }
     catch (error) {
-        throw new Error("The reviewed Helyx update catalogue was invalid", {
+        throw new Error("The reviewed Helyx self-host catalogue was invalid", {
             cause: error,
         });
     }
 }
+async function readBoundedCatalogueBody(response) {
+    if (!response.body) {
+        throw new Error("The reviewed Helyx self-host catalogue was empty");
+    }
+    const reader = response.body.getReader();
+    const chunks = [];
+    let totalBytes = 0;
+    try {
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            totalBytes += value.byteLength;
+            if (totalBytes > maximumCatalogueBytes) {
+                throw new Error("The reviewed Helyx self-host catalogue was too large");
+            }
+            chunks.push(value);
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+    if (totalBytes === 0) {
+        throw new Error("The reviewed Helyx self-host catalogue was empty");
+    }
+    const bytes = new Uint8Array(totalBytes);
+    let offset = 0;
+    for (const chunk of chunks) {
+        bytes.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+}
 function targetHelyxDependencies(catalogue, selection) {
     if (catalogue.core.availability !== "published" ||
         catalogue.generator.availability !== "published") {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@helyx/cli",
-  "version": "0.3.0",
+  "version": "0.3.3",
   "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.2",
-    "@helyx/config": "0.2.1",
-    "@helyx/database": "0.2.1",
+    "@helyx/bot": "0.3.0",
+    "@helyx/config": "0.3.0",
+    "@helyx/database": "0.3.0",
     "semver": "7.8.5",
     "zod": "4.4.3"
   },

package/self-host-catalogue.json

@@ -1,14 +1,14 @@
 {
   "schemaVersion": 1,
-  "catalogueVersion": 11,
+  "catalogueVersion": 12,
   "core": {
     "package": "@helyx/bot",
-    "version": "0.2.2",
+    "version": "0.3.0",
     "availability": "published"
   },
   "generator": {
     "package": "@helyx/cli",
-    "version": "0.3.0",
+    "version": "0.3.3",
     "command": "helyx",
     "availability": "published"
   },
@@ -16,7 +16,7 @@
     {
       "id": "helyx.feedback",
       "package": "@helyx/module-feedback",
-      "version": "1.0.5",
+      "version": "1.1.0",
       "name": "Feedback",
       "description": "Collects simple feedback from Discord server members.",
       "category": "Community",
@@ -26,7 +26,7 @@
     {
       "id": "helyx.welcome",
       "package": "@helyx/module-welcome",
-      "version": "1.0.5",
+      "version": "1.1.0",
       "name": "Welcome",
       "description": "Greets new members and can give them a starting role.",
       "category": "Community",
@@ -36,7 +36,7 @@
     {
       "id": "helyx.suggestions",
       "package": "@helyx/module-suggestions",
-      "version": "1.0.5",
+      "version": "1.1.0",
       "name": "Suggestions",
       "description": "Collects community ideas with configurable reaction or button voting.",
       "category": "Community",
@@ -101,15 +101,14 @@
       "description": "Add a deliberate member verification step.",
       "category": "Safety",
       "availability": "planned",
-      "releaseStatus": "testing",
-      "tier": "premium"
+      "releaseStatus": "planned"
     },
     {
-      "id": "helyx.antiraid",
-      "package": "@helyx/module-antiraid",
+      "id": "helyx.raid-protection",
+      "package": "@helyx/module-raid-protection",
       "version": null,
-      "name": "Raid protection",
-      "description": "Detect and slow unusual join activity.",
+      "name": "Raid Protection",
+      "description": "Manually remove selected new activity during a raid.",
       "category": "Safety",
       "availability": "planned",
       "releaseStatus": "planned"
@@ -237,7 +236,7 @@
     {
       "id": "helyx.logging",
       "package": "@helyx/module-logging",
-      "version": "1.0.5",
+      "version": "1.1.0",
       "name": "Logging",
       "description": "Posts configurable activity records from enabled Helyx modules.",
       "category": "Insights",

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

@@ -37,6 +37,12 @@ LOG_LEVEL=info
 # HELYX_BOT_CONTROL_SECRET=replace-with-a-base64-encoded-32-byte-key
 # HELYX_BOT_CONTROL_PORT=3001
 
+# Privacy tooling ships with self-hosted Helyx but stays disabled until the
+# dedicated least-privilege executor connection has been configured.
+HELYX_PRIVACY_ENABLED=false
+# HELYX_PRIVACY_EXECUTOR_DATABASE_URL=<dedicated-privacy-executor-postgresql-url>
+# HELYX_PRIVACY_EXECUTOR_DATABASE_SSL=disable
+
 # 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