@helyx/cli 0.1.0

package/README.md

@@ -0,0 +1,16 @@
+# Helyx CLI
+
+The private, unpublished Helyx distribution entry point.
+
+```text
+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.
+
+`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.
+
+The package remains `private` and `UNLICENSED`; it must not be published until the repository licence and publication gates are approved.

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.js

@@ -0,0 +1,85 @@
+#!/usr/bin/env node
+import { loadConfiguredModulePackages, resolveModulePackageSpecifiers, startBot, } from "@helyx/bot";
+import { parseBotEnvironment, parseDatabaseEnvironment } from "@helyx/config";
+import { checkDatabaseConnection, createDatabasePool, inspectCoreMigrations, runCoreMigrations, } from "@helyx/database";
+import { runSelfHostCommand } from "./self-host/command.js";
+const command = process.argv[2];
+try {
+    if (command === "start") {
+        await startBot();
+    }
+    else if (command === "migrate") {
+        await migrate();
+    }
+    else if (command === "doctor") {
+        await doctor();
+    }
+    else if (command === "self-host") {
+        await runSelfHostCommand(process.argv.slice(3));
+    }
+    else if (command === "help" || command === "--help" || command === "-h") {
+        printHelp();
+    }
+    else {
+        printHelp();
+        if (command)
+            throw new Error(`Unknown command: ${command}`);
+        process.exitCode = 1;
+    }
+}
+catch (error) {
+    const value = error instanceof Error ? error : new Error(String(error));
+    console.error(`Helyx ${command ?? "command"} failed: ${value.message}`);
+    process.exitCode = 1;
+}
+async function migrate() {
+    const environment = parseDatabaseEnvironment(process.env);
+    const database = createDatabasePool({
+        connectionString: environment.DATABASE_URL,
+        sslMode: environment.DATABASE_SSL,
+        applicationName: "helyx-cli-migrate",
+        maxConnections: 1,
+    });
+    try {
+        await checkDatabaseConnection(database);
+        const result = await runCoreMigrations(database);
+        console.log(`Core database ready: ${result.applied.length} applied, ${result.verified.length} verified.`);
+    }
+    finally {
+        await database.end();
+    }
+}
+async function doctor() {
+    const environment = parseBotEnvironment(process.env);
+    const database = createDatabasePool({
+        connectionString: environment.DATABASE_URL,
+        sslMode: environment.DATABASE_SSL,
+        applicationName: "helyx-cli-doctor",
+        maxConnections: 1,
+    });
+    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.`);
+    }
+    finally {
+        await database.end();
+    }
+}
+function printHelp() {
+    console.log(`Usage: helyx <command>
+
+Commands:
+  start    Start the Helyx Discord bot
+  migrate  Apply core PostgreSQL migrations and exit
+  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
+  help     Show this help`);
+}
+//# sourceMappingURL=cli.js.map

package/dist/index.d.ts

@@ -0,0 +1,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";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,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";
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1,72 @@
+import { z } from "zod";
+export declare const selfHostCategories: readonly ["Community", "Safety", "Support", "Automation", "Engagement", "Insights", "Integrations"];
+export declare const selfHostModuleSchema: z.ZodObject<{
+    id: z.ZodString;
+    package: z.ZodString;
+    version: z.ZodNullable<z.ZodString>;
+    name: z.ZodString;
+    description: z.ZodString;
+    category: z.ZodEnum<{
+        Community: "Community";
+        Safety: "Safety";
+        Support: "Support";
+        Automation: "Automation";
+        Engagement: "Engagement";
+        Insights: "Insights";
+        Integrations: "Integrations";
+    }>;
+    availability: z.ZodEnum<{
+        planned: "planned";
+        unpublished: "unpublished";
+        published: "published";
+    }>;
+}, z.core.$strict>;
+export declare const selfHostCatalogueSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    catalogueVersion: z.ZodNumber;
+    core: z.ZodObject<{
+        package: z.ZodString;
+        version: z.ZodString;
+        availability: z.ZodEnum<{
+            unpublished: "unpublished";
+            published: "published";
+        }>;
+    }, z.core.$strict>;
+    generator: z.ZodObject<{
+        package: z.ZodString;
+        version: z.ZodString;
+        availability: z.ZodEnum<{
+            unpublished: "unpublished";
+            published: "published";
+        }>;
+        command: z.ZodString;
+    }, z.core.$strict>;
+    modules: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        package: z.ZodString;
+        version: z.ZodNullable<z.ZodString>;
+        name: z.ZodString;
+        description: z.ZodString;
+        category: z.ZodEnum<{
+            Community: "Community";
+            Safety: "Safety";
+            Support: "Support";
+            Automation: "Automation";
+            Engagement: "Engagement";
+            Insights: "Insights";
+            Integrations: "Integrations";
+        }>;
+        availability: z.ZodEnum<{
+            planned: "planned";
+            unpublished: "unpublished";
+            published: "published";
+        }>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type SelfHostModule = z.infer<typeof selfHostModuleSchema>;
+export type SelfHostCatalogue = z.infer<typeof selfHostCatalogueSchema>;
+export declare function parseSelfHostCatalogue(input: unknown): SelfHostCatalogue;
+export declare function loadSelfHostCatalogue(path: string | URL, reader?: (path: string | URL, encoding: "utf8") => Promise<string>): Promise<SelfHostCatalogue>;
+export declare function bundledSelfHostCatalogueUrl(): URL;
+export declare function loadBundledSelfHostCatalogue(): Promise<SelfHostCatalogue>;
+//# sourceMappingURL=catalogue.d.ts.map

package/dist/self-host/catalogue.js

@@ -0,0 +1,115 @@
+import semver from "semver";
+import { readFile } from "node:fs/promises";
+import { z } from "zod";
+export const selfHostCategories = [
+    "Community",
+    "Safety",
+    "Support",
+    "Automation",
+    "Engagement",
+    "Insights",
+    "Integrations",
+];
+const exactVersion = z
+    .string()
+    .refine((value) => semver.valid(value) === value, "must be exact semver");
+const helyxPackage = z
+    .string()
+    .regex(/^@helyx\/[a-z0-9][a-z0-9-]*$/u, "must be an official Helyx package");
+const modulePackage = z
+    .string()
+    .regex(/^@helyx\/module-[a-z0-9][a-z0-9-]*$/u, "must be an official Helyx module package");
+const moduleId = z
+    .string()
+    .regex(/^helyx\.[a-z0-9][a-z0-9-]*$/u, "must be a Helyx module ID");
+const availability = z.enum(["planned", "unpublished", "published"]);
+const componentSchema = z
+    .object({
+    package: helyxPackage,
+    version: exactVersion,
+    availability: z.enum(["unpublished", "published"]),
+})
+    .strict();
+const generatorSchema = componentSchema
+    .extend({
+    command: z
+        .string()
+        .regex(/^[a-z][a-z0-9-]*$/u)
+        .max(40),
+})
+    .strict();
+export const selfHostModuleSchema = z
+    .object({
+    id: moduleId,
+    package: modulePackage,
+    version: exactVersion.nullable(),
+    name: z.string().trim().min(1).max(80),
+    description: z.string().trim().min(1).max(300),
+    category: z.enum(selfHostCategories),
+    availability,
+})
+    .strict()
+    .superRefine((module, context) => {
+    if (module.availability === "planned" && module.version !== null) {
+        context.addIssue({
+            code: "custom",
+            path: ["version"],
+            message: "must be null while a module is planned",
+        });
+    }
+    if (module.availability !== "planned" && module.version === null) {
+        context.addIssue({
+            code: "custom",
+            path: ["version"],
+            message: "must be exact semver for an implemented module",
+        });
+    }
+});
+export const selfHostCatalogueSchema = z
+    .object({
+    schemaVersion: z.literal(1),
+    catalogueVersion: z.number().int().positive(),
+    core: componentSchema,
+    generator: generatorSchema,
+    modules: z.array(selfHostModuleSchema),
+})
+    .strict()
+    .superRefine((catalogue, context) => {
+    const ids = new Set();
+    const packages = new Set([
+        catalogue.core.package,
+        catalogue.generator.package,
+    ]);
+    for (const [index, module] of catalogue.modules.entries()) {
+        if (ids.has(module.id)) {
+            context.addIssue({
+                code: "custom",
+                path: ["modules", index, "id"],
+                message: `duplicate module ID: ${module.id}`,
+            });
+        }
+        if (packages.has(module.package)) {
+            context.addIssue({
+                code: "custom",
+                path: ["modules", index, "package"],
+                message: `duplicate package name: ${module.package}`,
+            });
+        }
+        ids.add(module.id);
+        packages.add(module.package);
+    }
+});
+export function parseSelfHostCatalogue(input) {
+    return selfHostCatalogueSchema.parse(input);
+}
+export async function loadSelfHostCatalogue(path, reader = readFile) {
+    const source = await reader(path, "utf8");
+    return parseSelfHostCatalogue(JSON.parse(source));
+}
+export function bundledSelfHostCatalogueUrl() {
+    return new URL("../../self-host-catalogue.json", import.meta.url);
+}
+export async function loadBundledSelfHostCatalogue() {
+    return loadSelfHostCatalogue(bundledSelfHostCatalogueUrl());
+}
+//# sourceMappingURL=catalogue.js.map

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

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

package/dist/self-host/command.js

@@ -0,0 +1,76 @@
+import { readFile, stat } from "node:fs/promises";
+import { resolve } from "node:path";
+import { loadBundledSelfHostCatalogue } from "./catalogue.js";
+import { generateSelfHostProject, } from "./project-generator.js";
+const maximumManifestBytes = 16 * 1_024;
+export async function runSelfHostCommand(arguments_) {
+    const [subcommand, ...rest] = arguments_;
+    if (subcommand !== "init") {
+        throw new Error("Usage: helyx self-host init --manifest <path> [--output <path>] [--install]");
+    }
+    const parsed = parseSelfHostInitArguments(rest);
+    const manifestPath = resolve(parsed.manifestPath);
+    const metadata = await stat(manifestPath);
+    if (!metadata.isFile() || metadata.size > maximumManifestBytes) {
+        throw new Error("Self-host build manifest must be a file no larger than 16 KB");
+    }
+    let manifest;
+    try {
+        manifest = JSON.parse(await readFile(manifestPath, "utf8"));
+    }
+    catch (error) {
+        throw new Error("Self-host build manifest is not valid JSON", {
+            cause: error,
+        });
+    }
+    const catalogue = await loadBundledSelfHostCatalogue();
+    const generated = await generateSelfHostProject({
+        catalogue,
+        manifest,
+        targetDirectory: parsed.outputPath,
+        install: parsed.install,
+    });
+    console.log(`Created Helyx Self-Hosted starter at ${generated.directory}`);
+    return generated;
+}
+export function parseSelfHostInitArguments(arguments_) {
+    let manifestPath;
+    let outputPath = "./helyx";
+    let outputConfigured = false;
+    let install = false;
+    for (let index = 0; index < arguments_.length; index += 1) {
+        const argument = arguments_[index];
+        if (argument === "--install") {
+            if (install)
+                throw new Error("--install may be specified only once");
+            install = true;
+            continue;
+        }
+        if (argument === "--manifest" || argument === "--output") {
+            const value = arguments_[index + 1];
+            if (!value || value.startsWith("--")) {
+                throw new Error(`${argument} requires a path`);
+            }
+            index += 1;
+            if (argument === "--manifest") {
+                if (manifestPath) {
+                    throw new Error("--manifest may be specified only once");
+                }
+                manifestPath = value;
+            }
+            else {
+                if (outputConfigured) {
+                    throw new Error("--output may be specified only once");
+                }
+                outputPath = value;
+                outputConfigured = true;
+            }
+            continue;
+        }
+        throw new Error(`Unknown self-host init option: ${argument ?? ""}`);
+    }
+    if (!manifestPath)
+        throw new Error("--manifest is required");
+    return { manifestPath, outputPath, install };
+}
+//# sourceMappingURL=command.js.map

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

@@ -0,0 +1,23 @@
+import { z } from "zod";
+import type { SelfHostCatalogue } from "./catalogue.js";
+export declare const selfHostBuildManifestSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    catalogueVersion: z.ZodNumber;
+    core: z.ZodObject<{
+        package: z.ZodString;
+        version: z.ZodString;
+    }, z.core.$strict>;
+    generator: z.ZodObject<{
+        package: z.ZodString;
+        version: z.ZodString;
+    }, z.core.$strict>;
+    modules: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        package: z.ZodString;
+        version: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type SelfHostBuildManifest = z.infer<typeof selfHostBuildManifestSchema>;
+export declare function createSelfHostBuildManifest(catalogue: SelfHostCatalogue, selectedModuleIds: readonly string[]): SelfHostBuildManifest;
+export declare function parseSelfHostBuildManifest(input: unknown, catalogue: SelfHostCatalogue): SelfHostBuildManifest;
+//# sourceMappingURL=manifest.d.ts.map

package/dist/self-host/manifest.js

@@ -0,0 +1,127 @@
+import semver from "semver";
+import { z } from "zod";
+const exactVersion = z
+    .string()
+    .refine((value) => semver.valid(value) === value, "must be exact semver");
+const officialPackage = z.string().regex(/^@helyx\/[a-z0-9][a-z0-9-]*$/u);
+const officialModulePackage = z
+    .string()
+    .regex(/^@helyx\/module-[a-z0-9][a-z0-9-]*$/u);
+const moduleId = z.string().regex(/^helyx\.[a-z0-9][a-z0-9-]*$/u);
+const buildComponentSchema = z
+    .object({ package: officialPackage, version: exactVersion })
+    .strict();
+const buildModuleSchema = z
+    .object({
+    id: moduleId,
+    package: officialModulePackage,
+    version: exactVersion,
+})
+    .strict();
+export const selfHostBuildManifestSchema = z
+    .object({
+    schemaVersion: z.literal(1),
+    catalogueVersion: z.number().int().positive(),
+    core: buildComponentSchema,
+    generator: buildComponentSchema,
+    modules: z.array(buildModuleSchema),
+})
+    .strict()
+    .superRefine((manifest, context) => {
+    const ids = new Set();
+    const packages = new Set();
+    for (const [index, module] of manifest.modules.entries()) {
+        if (ids.has(module.id)) {
+            context.addIssue({
+                code: "custom",
+                path: ["modules", index, "id"],
+                message: `duplicate module ID: ${module.id}`,
+            });
+        }
+        if (packages.has(module.package)) {
+            context.addIssue({
+                code: "custom",
+                path: ["modules", index, "package"],
+                message: `duplicate module package: ${module.package}`,
+            });
+        }
+        ids.add(module.id);
+        packages.add(module.package);
+    }
+});
+export function createSelfHostBuildManifest(catalogue, selectedModuleIds) {
+    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");
+    }
+    const byId = new Map(catalogue.modules.map((module) => [module.id, module]));
+    const modules = [...selectedModuleIds]
+        .sort((left, right) => left.localeCompare(right, "en"))
+        .map((id) => {
+        const module = byId.get(id);
+        if (!module)
+            throw new Error(`Unknown self-host module: ${id}`);
+        if (module.availability !== "published" || module.version === null) {
+            throw new Error(`Self-host module is not published: ${id}`);
+        }
+        return {
+            id: module.id,
+            package: module.package,
+            version: module.version,
+        };
+    });
+    return {
+        schemaVersion: 1,
+        catalogueVersion: catalogue.catalogueVersion,
+        core: {
+            package: catalogue.core.package,
+            version: catalogue.core.version,
+        },
+        generator: {
+            package: catalogue.generator.package,
+            version: catalogue.generator.version,
+        },
+        modules,
+    };
+}
+export function parseSelfHostBuildManifest(input, catalogue) {
+    const manifest = selfHostBuildManifestSchema.parse(input);
+    if (manifest.catalogueVersion !== catalogue.catalogueVersion) {
+        throw new Error(`Unsupported self-host catalogue version: ${manifest.catalogueVersion}`);
+    }
+    assertPublishedComponent(catalogue.core, "Helyx runtime");
+    assertPublishedComponent(catalogue.generator, "Helyx generator");
+    assertComponentMatches(manifest.core, catalogue.core, "runtime");
+    assertComponentMatches(manifest.generator, catalogue.generator, "generator");
+    const byId = new Map(catalogue.modules.map((module) => [module.id, module]));
+    for (const selected of manifest.modules) {
+        const module = byId.get(selected.id);
+        if (!module ||
+            module.availability !== "published" ||
+            module.version === null ||
+            module.package !== selected.package ||
+            module.version !== selected.version) {
+            throw new Error(`Build manifest module is unavailable or does not match the trusted catalogue: ${selected.id}`);
+        }
+    }
+    if (manifest.modules.length > catalogue.modules.length) {
+        throw new Error("Build manifest contains too many modules");
+    }
+    return {
+        ...manifest,
+        modules: [...manifest.modules].sort((left, right) => left.id.localeCompare(right.id, "en")),
+    };
+}
+function assertPublishedComponent(component, label) {
+    if (component.availability !== "published") {
+        throw new Error(`${label} is not published`);
+    }
+}
+function assertComponentMatches(selected, expected, label) {
+    if (selected.package !== expected.package ||
+        selected.version !== expected.version) {
+        throw new Error(`Build manifest ${label} does not match the trusted catalogue`);
+    }
+}
+//# sourceMappingURL=manifest.js.map

package/dist/self-host/project-generator.d.ts

@@ -0,0 +1,24 @@
+import type { BotEnvironmentInput } from "@helyx/config";
+import type { SelfHostCatalogue } from "./catalogue.js";
+import { type SelfHostBuildManifest } from "./manifest.js";
+export type SelfHostCommandRunner = (arguments_: readonly string[], workingDirectory: string) => Promise<void>;
+export interface GenerateSelfHostProjectOptions {
+    catalogue: SelfHostCatalogue;
+    manifest: unknown;
+    targetDirectory: string;
+    install?: boolean;
+    commandRunner?: SelfHostCommandRunner;
+}
+export interface GeneratedSelfHostProject {
+    directory: string;
+    manifest: SelfHostBuildManifest;
+    files: string[];
+}
+export declare function generateSelfHostProject(options: GenerateSelfHostProjectOptions): Promise<GeneratedSelfHostProject>;
+type EnvironmentExample = Record<keyof BotEnvironmentInput, {
+    value: string;
+    optional: boolean;
+}>;
+export declare const selfHostEnvironmentContract: EnvironmentExample;
+export {};
+//# sourceMappingURL=project-generator.d.ts.map