@helyx/cli 1.4.3 → 1.6.0

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## 1.6.0
+
+### Minor Changes
+
+- b698422: Add the optional `helyx envbuilder` command and generated starter npm script.
+  Preserve platform builder selections in build manifests and include standalone
+  batch, PowerShell or POSIX scripts only when selected. The guided builder runs
+  locally, checks input format, masks saved credentials and preserves encryption
+  keys and custom settings until the operator confirms saving.
+
+## 1.5.0
+
+### Minor Changes
+
+- Publish the coordinated shared contracts, scheduler admission repair, command-root renaming and restricted-word policy support, database repositories and migrations, and module runtime corrections. Align compatible internal dependency bands so public consumers install the updated shared contracts. Preserve private Testing and Alpha release states.
+
+### Patch Changes
+
+- Updated dependencies
+  - @helyx/config@1.6.0
+  - @helyx/database@2.5.0
+
 ## 1.4.3
 
 ### Patch Changes

package/README.md

@@ -20,6 +20,12 @@ operation supports a local or hosted PostgreSQL or MySQL-compatible database.
 and performs the bot bootstrap, including core and installed-module migrations.
 `migrate` applies only core migrations and exits.
 
+Generated starters also include the optional `npm run envbuilder` command.
+After `npm ci`, it runs `helyx envbuilder`, a local guided `.env` builder with
+no connection tests. Additional standalone Windows batch, PowerShell and
+macOS/Linux scripts are included only when selected for the download. Setup
+and startup remain independent.
+
 `doctor` checks the complete bot environment, connectivity, immutable core
 migration history, package metadata and selected module/engine compatibility
 without logging in to Discord or changing the database. It inspects module

package/dist/cli.js

@@ -24,6 +24,10 @@ try {
     else if (command === "setup") {
         await setup();
     }
+    else if (command === "envbuilder") {
+        const builder = (await import(new URL("../templates/self-host/env-builder.mjs", import.meta.url).href));
+        await builder.runEnvironmentBuilder(process.argv[3]);
+    }
     else if (command === "self-host") {
         await runSelfHostCommand(process.argv.slice(3));
     }
@@ -141,6 +145,7 @@ function printHelp() {
 
 Commands:
   setup    Create .env safely and explain the available hosting paths
+  envbuilder  Optionally create or update .env with a local guided builder
   start    Start the Helyx Discord bot
   migrate  Apply core migrations for the selected database engine and exit
   doctor   Validate environment, database schema and module packages

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 export * from "./self-host/catalogue.js";
 export * from "./self-host/command.js";
 export * from "./self-host/database-adapters.js";
+export * from "./self-host/environment-builders.js";
 export * from "./self-host/manifest.js";
 export * from "./self-host/project-generator.js";
 export * from "./self-host/update.js";

package/dist/index.js

@@ -1,6 +1,7 @@
 export * from "./self-host/catalogue.js";
 export * from "./self-host/command.js";
 export * from "./self-host/database-adapters.js";
+export * from "./self-host/environment-builders.js";
 export * from "./self-host/manifest.js";
 export * from "./self-host/project-generator.js";
 export * from "./self-host/update.js";

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

@@ -2,6 +2,7 @@ import { z } from "zod";
 export declare const selfHostCategories: readonly ["Community", "Safety", "Support & Staff", "Auto Tools", "Automation", "Engagement", "Gaming", "Insights", "Integrations"];
 export declare const selfHostReleaseStatusSchema: z.ZodEnum<{
     planned: "planned";
+    alpha: "alpha";
     testing: "testing";
     beta: "beta";
     live: "live";
@@ -35,6 +36,7 @@ export declare const selfHostModuleSchema: z.ZodObject<{
     }>;
     releaseStatus: z.ZodEnum<{
         planned: "planned";
+        alpha: "alpha";
         testing: "testing";
         beta: "beta";
         live: "live";
@@ -68,6 +70,7 @@ export declare const selfHostModuleV2Schema: z.ZodDiscriminatedUnion<[z.ZodObjec
     }>;
     releaseStatus: z.ZodEnum<{
         planned: "planned";
+        alpha: "alpha";
         testing: "testing";
         beta: "beta";
         live: "live";
@@ -122,6 +125,7 @@ export declare const selfHostModuleV2Schema: z.ZodDiscriminatedUnion<[z.ZodObjec
     }>;
     releaseStatus: z.ZodEnum<{
         planned: "planned";
+        alpha: "alpha";
         testing: "testing";
         beta: "beta";
         live: "live";
@@ -197,6 +201,7 @@ export declare const selfHostCatalogueSchema: z.ZodDiscriminatedUnion<[z.ZodObje
         }>;
         releaseStatus: z.ZodEnum<{
             planned: "planned";
+            alpha: "alpha";
             testing: "testing";
             beta: "beta";
             live: "live";
@@ -257,6 +262,7 @@ export declare const selfHostCatalogueSchema: z.ZodDiscriminatedUnion<[z.ZodObje
         }>;
         releaseStatus: z.ZodEnum<{
             planned: "planned";
+            alpha: "alpha";
             testing: "testing";
             beta: "beta";
             live: "live";
@@ -311,6 +317,7 @@ export declare const selfHostCatalogueSchema: z.ZodDiscriminatedUnion<[z.ZodObje
         }>;
         releaseStatus: z.ZodEnum<{
             planned: "planned";
+            alpha: "alpha";
             testing: "testing";
             beta: "beta";
             live: "live";

package/dist/self-host/catalogue.js

@@ -35,6 +35,7 @@ const moduleDependency = z
 const availability = z.enum(["planned", "unpublished", "published"]);
 export const selfHostReleaseStatusSchema = z.enum([
     "planned",
+    "alpha",
     "testing",
     "beta",
     "live",
@@ -118,6 +119,14 @@ export const selfHostModuleSchema = z
             message: "live modules must have an exact published version",
         });
     }
+    if (module.releaseStatus === "alpha" &&
+        module.availability !== "unpublished") {
+        context.addIssue({
+            code: "custom",
+            path: ["releaseStatus"],
+            message: "alpha scaffolds must remain unpublished",
+        });
+    }
     if (module.releaseStatus === "planned" &&
         module.availability !== "planned") {
         context.addIssue({

package/dist/self-host/environment-builders.d.ts

@@ -0,0 +1,12 @@
+import { z } from "zod";
+export declare const selfHostEnvironmentBuilderSchema: z.ZodEnum<{
+    none: "none";
+    windows: "windows";
+    powershell: "powershell";
+    unix: "unix";
+    all: "all";
+}>;
+export type SelfHostEnvironmentBuilder = z.infer<typeof selfHostEnvironmentBuilderSchema>;
+export type SelfHostEnvironmentBuilderFile = "env-builder.mjs" | "env-builder.bat" | "env-builder.ps1" | "env-builder.sh";
+export declare function selfHostEnvironmentBuilderFiles(selection?: SelfHostEnvironmentBuilder): SelfHostEnvironmentBuilderFile[];
+//# sourceMappingURL=environment-builders.d.ts.map

package/dist/self-host/environment-builders.js

@@ -0,0 +1,25 @@
+import { z } from "zod";
+export const selfHostEnvironmentBuilderSchema = z.enum([
+    "none",
+    "windows",
+    "powershell",
+    "unix",
+    "all",
+]);
+export function selfHostEnvironmentBuilderFiles(selection = "none") {
+    selfHostEnvironmentBuilderSchema.parse(selection);
+    if (selection === "none")
+        return [];
+    const launchers = {
+        windows: "env-builder.bat",
+        powershell: "env-builder.ps1",
+        unix: "env-builder.sh",
+    };
+    return [
+        "env-builder.mjs",
+        ...(selection === "all"
+            ? Object.values(launchers)
+            : [launchers[selection]]),
+    ];
+}
+//# sourceMappingURL=environment-builders.js.map

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

@@ -1,7 +1,15 @@
 import { z } from "zod";
+import { type SelfHostEnvironmentBuilder } from "./environment-builders.js";
 import { type SelfHostCatalogue, type SelfHostDatabaseEngine } from "./catalogue.js";
 export declare const selfHostBuildManifestSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     schemaVersion: z.ZodLiteral<1>;
+    environmentBuilder: z.ZodOptional<z.ZodEnum<{
+        none: "none";
+        windows: "windows";
+        powershell: "powershell";
+        unix: "unix";
+        all: "all";
+    }>>;
     catalogueVersion: z.ZodNumber;
     core: z.ZodObject<{
         package: z.ZodString;
@@ -18,6 +26,13 @@ export declare const selfHostBuildManifestSchema: z.ZodDiscriminatedUnion<[z.Zod
     }, z.core.$strict>>;
 }, z.core.$strict>, z.ZodObject<{
     schemaVersion: z.ZodLiteral<2>;
+    environmentBuilder: z.ZodOptional<z.ZodEnum<{
+        none: "none";
+        windows: "windows";
+        powershell: "powershell";
+        unix: "unix";
+        all: "all";
+    }>>;
     databaseEngine: z.ZodOptional<z.ZodEnum<{
         postgresql: "postgresql";
         mysql: "mysql";
@@ -52,6 +67,6 @@ export declare const selfHostBuildManifestSchema: z.ZodDiscriminatedUnion<[z.Zod
     }, z.core.$strict>>;
 }, z.core.$strict>], "schemaVersion">;
 export type SelfHostBuildManifest = z.infer<typeof selfHostBuildManifestSchema>;
-export declare function createSelfHostBuildManifest(catalogue: SelfHostCatalogue, selectedModuleIds: readonly string[], databaseEngine?: SelfHostDatabaseEngine): SelfHostBuildManifest;
+export declare function createSelfHostBuildManifest(catalogue: SelfHostCatalogue, selectedModuleIds: readonly string[], databaseEngine?: SelfHostDatabaseEngine, environmentBuilder?: SelfHostEnvironmentBuilder): SelfHostBuildManifest;
 export declare function parseSelfHostBuildManifest(input: unknown, catalogue: SelfHostCatalogue): SelfHostBuildManifest;
 //# sourceMappingURL=manifest.d.ts.map

package/dist/self-host/manifest.js

@@ -1,6 +1,7 @@
 import semver from "semver";
 import { isDeepStrictEqual } from "node:util";
 import { z } from "zod";
+import { selfHostEnvironmentBuilderSchema, } from "./environment-builders.js";
 import { isSelfHostModuleCustomerSelectable, selfHostDatabaseEngineSchema, } from "./catalogue.js";
 const exactVersion = z
     .string()
@@ -23,6 +24,7 @@ const buildModuleSchema = z
 const selfHostBuildManifestV1Schema = z
     .object({
     schemaVersion: z.literal(1),
+    environmentBuilder: selfHostEnvironmentBuilderSchema.optional(),
     catalogueVersion: z.number().int().positive(),
     core: buildComponentSchema,
     generator: buildComponentSchema,
@@ -48,6 +50,7 @@ const buildModuleV2Schema = buildModuleSchema
 const selfHostBuildManifestV2Schema = z
     .object({
     schemaVersion: z.literal(2),
+    environmentBuilder: selfHostEnvironmentBuilderSchema.optional(),
     databaseEngine: selfHostDatabaseEngineSchema.optional(),
     catalogueVersion: z.number().int().positive(),
     core: buildComponentSchema,
@@ -82,15 +85,16 @@ export const selfHostBuildManifestSchema = z
         packages.add(module.package);
     }
 });
-export function createSelfHostBuildManifest(catalogue, selectedModuleIds, databaseEngine = "postgresql") {
+export function createSelfHostBuildManifest(catalogue, selectedModuleIds, databaseEngine = "postgresql", environmentBuilder = "none") {
     selfHostDatabaseEngineSchema.parse(databaseEngine);
+    selfHostEnvironmentBuilderSchema.parse(environmentBuilder);
     assertPublishedComponent(catalogue.core, "Helyx runtime");
     assertPublishedComponent(catalogue.generator, "Helyx generator");
     if (new Set(selectedModuleIds).size !== selectedModuleIds.length) {
         throw new Error("Self-host selection contains duplicate module IDs");
     }
     if (catalogue.schemaVersion === 2) {
-        return createSelfHostBuildManifestV2(catalogue, selectedModuleIds, databaseEngine);
+        return createSelfHostBuildManifestV2(catalogue, selectedModuleIds, databaseEngine, environmentBuilder);
     }
     if (databaseEngine !== "postgresql") {
         throw new Error("Legacy self-host catalogue supports PostgreSQL only");
@@ -115,6 +119,7 @@ export function createSelfHostBuildManifest(catalogue, selectedModuleIds, databa
     });
     return {
         schemaVersion: 1,
+        ...(environmentBuilder !== "none" ? { environmentBuilder } : {}),
         catalogueVersion: catalogue.catalogueVersion,
         core: {
             package: catalogue.core.package,
@@ -127,7 +132,7 @@ export function createSelfHostBuildManifest(catalogue, selectedModuleIds, databa
         modules,
     };
 }
-function createSelfHostBuildManifestV2(catalogue, selectedModuleIds, databaseEngine) {
+function createSelfHostBuildManifestV2(catalogue, selectedModuleIds, databaseEngine, environmentBuilder = "none") {
     const byId = new Map(catalogue.modules.map((module) => [module.id, module]));
     const explicitlySelected = new Set(selectedModuleIds);
     const modules = [];
@@ -189,6 +194,7 @@ function createSelfHostBuildManifestV2(catalogue, selectedModuleIds, databaseEng
         include(id);
     return {
         schemaVersion: 2,
+        ...(environmentBuilder !== "none" ? { environmentBuilder } : {}),
         ...(databaseEngine === "mysql" ? { databaseEngine } : {}),
         catalogueVersion: catalogue.catalogueVersion,
         core: {
@@ -218,13 +224,20 @@ export function parseSelfHostBuildManifest(input, catalogue) {
         const selectedModuleIds = manifest.modules
             .filter(({ moduleKind }) => moduleKind === "customer_feature")
             .map(({ id }) => id);
-        const expected = createSelfHostBuildManifestV2(catalogue, selectedModuleIds, manifest.databaseEngine ?? "postgresql");
+        const expected = createSelfHostBuildManifestV2(catalogue, selectedModuleIds, manifest.databaseEngine ?? "postgresql", manifest.environmentBuilder ?? "none");
         if (!isDeepStrictEqual({
             ...manifest,
+            environmentBuilder: manifest.environmentBuilder === "none"
+                ? undefined
+                : manifest.environmentBuilder,
             databaseEngine: manifest.databaseEngine === "postgresql"
                 ? undefined
                 : manifest.databaseEngine,
-        }, { ...expected, databaseEngine: expected.databaseEngine })) {
+        }, {
+            ...expected,
+            databaseEngine: expected.databaseEngine,
+            environmentBuilder: expected.environmentBuilder,
+        })) {
             throw new Error("Build manifest modules do not match the trusted catalogue dependency graph");
         }
         return expected;

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

@@ -2,6 +2,7 @@ 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 { selfHostEnvironmentBuilderFiles, } from "./environment-builders.js";
 import { isSelfHostModuleCustomerSelectable, } from "./catalogue.js";
 import { parseSelfHostBuildManifest, } from "./manifest.js";
 import { databaseAdaptersForCatalogue, } from "./database-adapters.js";
@@ -80,6 +81,7 @@ async function writeGeneratedFiles(targetDirectory, manifest, catalogue, databas
         engines: { node: ">=24 <27", npm: ">=11" },
         scripts: {
             setup: "helyx setup",
+            envbuilder: "helyx envbuilder",
             start: "helyx start",
             doctor: "helyx doctor",
             migrate: "helyx migrate",
@@ -95,7 +97,10 @@ async function writeGeneratedFiles(targetDirectory, manifest, catalogue, databas
     };
     await writeFile(resolve(targetDirectory, "package.json"), formatJson(packageJson), "utf8");
     await writeFile(resolve(targetDirectory, "helyx.modules.json"), formatJson(moduleCatalogue), "utf8");
-    for (const fileName of generatedFileNames) {
+    for (const fileName of [
+        ...generatedFileNames,
+        ...selfHostEnvironmentBuilderFiles(manifest.environmentBuilder),
+    ]) {
         const template = await readFile(fileName === "compose.yaml" && databaseEngine === "mysql"
             ? mysqlComposeTemplateUrl()
             : templateUrl(fileName), "utf8");
@@ -106,8 +111,13 @@ async function writeGeneratedFiles(targetDirectory, manifest, catalogue, databas
                 : template;
         if (fileName === ".env.example")
             validateEnvironmentTemplate(rendered, databaseEngine);
-        const content = normalizeCrLf(rendered);
-        await writeFile(resolve(targetDirectory, fileName), content, "utf8");
+        const content = fileName.endsWith(".sh")
+            ? rendered.replaceAll("\r\n", "\n")
+            : normalizeCrLf(rendered);
+        await writeFile(resolve(targetDirectory, fileName), content, {
+            encoding: "utf8",
+            mode: fileName.endsWith(".sh") ? 0o755 : 0o644,
+        });
     }
 }
 function renderEnvironmentExample(template, databaseEngine) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@helyx/cli",
-  "version": "1.4.3",
+  "version": "1.6.0",
   "description": "Command-line tools for running and generating self-hosted Helyx deployments.",
   "keywords": [
     "helyx",
@@ -53,15 +53,15 @@
   },
   "dependencies": {
     "@helyx/bot": ">=1.5.2 <2.0.0",
-    "@helyx/config": ">=1.4.0 <2.0.0",
-    "@helyx/database": ">=2.4.1 <3.0.0",
+    "@helyx/config": ">=1.6.0 <2.0.0",
+    "@helyx/database": ">=2.5.0 <3.0.0",
     "semver": "7.8.5",
-    "zod": "4.4.3"
+    "zod": "4.6.7"
   },
   "optionalDependencies": {
-    "@helyx/database-mysql": ">=0.2.1 <0.3.0"
+    "@helyx/database-mysql": ">=0.3.0 <0.4.0"
   },
   "devDependencies": {
-    "@types/semver": "7.7.1"
+    "@types/semver": "7.8.0"
   }
 }