@helyx/bot 0.4.37 → 0.4.39

package/documentation/runbooks/installation-and-upgrades.md

@@ -0,0 +1,48 @@
+# Installation and upgrade runbook
+
+## First installation
+
+1. Generate the project with `helyx self-host init` and a reviewed build
+   manifest.
+2. Copy and complete `.env` with `helyx setup`.
+3. Install dependencies with `npm ci` if they were not installed during
+   generation.
+4. Run `npm run doctor` and resolve every error.
+5. Start the process and confirm database, Discord, and module health.
+6. Exercise one low-risk command in a test server before production use.
+
+## Upgrade
+
+1. Read the release notes and confirm the supported Node.js and npm versions.
+2. Create a current PostgreSQL backup and preserve the existing project
+   metadata and environment file.
+3. Stop the Helyx process cleanly.
+4. Preview the compatible release set:
+
+   ```sh
+   helyx self-host update --check
+   ```
+
+5. Apply it only after reviewing the complete change:
+
+   ```sh
+   helyx self-host update --confirm
+   npm ci
+   npm run doctor
+   ```
+
+6. Start Helyx and verify health, command availability, and one representative
+   workflow for every upgraded module.
+
+The updater backs up managed project metadata under `.helyx/backups` and does
+not change `.env` or customer database data. Database migrations can be
+forward-only. Never edit migration history or downgrade individual Helyx
+packages to simulate a rollback.
+
+## Failed validation
+
+Leave the process stopped, retain sanitized logs, and determine whether the
+failure is configuration, package integrity, database connectivity, or module
+compatibility. If the updater restored managed files, rerun `npm ci` and
+`npm run doctor` before restarting the previous version. Restore data only from
+a tested backup and only when the incident specifically requires it.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@helyx/bot",
-  "version": "0.4.37",
+  "version": "0.4.39",
   "description": "Production Discord runtime for the modular Helyx platform.",
   "keywords": [
     "helyx",
@@ -32,6 +32,7 @@
     "dist",
     "!dist/*.tsbuildinfo",
     "!dist/**/*.map",
+    "documentation",
     "CHANGELOG.md",
     "README.md",
     "LICENSE"
@@ -44,6 +45,7 @@
   },
   "scripts": {
     "build": "tsc -b",
+    "prepack": "node ../../scripts/public-documentation.mjs --sync-bot",
     "dev": "node --env-file-if-exists=../../.env --import tsx src/index.ts",
     "start": "node --env-file-if-exists=../../.env dist/index.js"
   },
@@ -51,17 +53,18 @@
     "@helyx/config": ">=0.5.0 <0.6.0",
     "@helyx/control-protocol": ">=0.4.0 <0.5.0",
     "@helyx/core": ">=0.1.0 <0.2.0",
-    "@helyx/database": ">=0.8.0 <0.9.0",
+    "@helyx/database": ">=0.8.6 <0.9.0",
     "@helyx/framework": ">=0.1.0 <0.2.0",
     "@helyx/module-manifest": ">=0.7.0 <0.8.0",
-    "@helyx/platform": ">=0.6.0 <0.7.0",
-    "@helyx/sdk": ">=0.8.0 <0.9.0",
+    "@helyx/platform": ">=0.6.2 <0.7.0",
+    "@helyx/sdk": ">=0.8.4 <0.9.0",
     "@helyx/status-client": ">=0.1.0 <0.2.0",
     "@helyx/verification-contracts": ">=0.3.0 <0.4.0",
     "discord.js": "14.27.0",
     "fastify": "5.10.0",
     "pino": "10.3.1",
     "redis": "6.1.0",
+    "undici": "6.28.0",
     "ws": "8.21.1",
     "zod": "4.4.3"
   },

package/dist/oauth-module.test.d.ts

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=oauth-module.test.d.ts.map

package/dist/oauth-module.test.js

@@ -1,172 +0,0 @@
-import { HELYX_SERVICE_NAMES, } from "@helyx/sdk";
-import { describe, expect, it, vi } from "vitest";
-import { createOAuthModule } from "./oauth-module.js";
-describe("global OAuth command", () => {
-    it("is global, guild-scoped and available without management permissions", () => {
-        const module = createOAuthModule();
-        const command = module.interactions?.commands?.[0];
-        const revoke = command?.subcommands?.[0];
-        expect(command).toMatchObject({
-            name: "oauth",
-            registration: "global",
-            contexts: ["guild"],
-            integrationTypes: ["guild_install"],
-        });
-        expect(revoke).toMatchObject({
-            name: "revoke",
-            rateLimit: { scope: "user", limit: 5, windowSeconds: 60 },
-        });
-        expect(module.manifest.permissions).toEqual([]);
-        expect(module.defaultPermissions?.commands["oauth.revoke"]).toMatchObject({
-            everyone: true,
-            requiredPermissions: [],
-        });
-    });
-    it("does not open a modal when the acting user has no connections", async () => {
-        const oauth = oauthService({ connections: [] });
-        const showModal = vi.fn();
-        const replies = [];
-        const command = createOAuthModule().interactions?.commands?.[0]?.subcommands?.[0];
-        await command?.execute(commandContext(oauth, {
-            showModal,
-            reply: (response) => {
-                replies.push(response);
-                return Promise.resolve();
-            },
-        }));
-        expect(showModal).not.toHaveBeenCalled();
-        expect(replies).toEqual([expect.objectContaining({ ephemeral: true })]);
-        expect(replies[0]?.componentsV2?.text?.[0]?.content).toContain("do not have any OAuth services");
-    });
-    it("uses opaque selections and requires explicit removal confirmation", async () => {
-        const oauth = oauthService({
-            connections: [
-                {
-                    selectionRef: "opaque-selection-reference-123",
-                    provider: "youtube",
-                    displayName: "Example creator",
-                    connectedAt: new Date().toISOString(),
-                },
-            ],
-        });
-        const showModal = vi.fn();
-        const command = createOAuthModule().interactions?.commands?.[0]?.subcommands?.[0];
-        await command?.execute(commandContext(oauth, { showModal }));
-        const modal = showModal.mock.calls[0]?.[0];
-        expect(modal?.title).toBe("Revoke OAuth access");
-        const service = modal?.items?.find((item) => "customId" in item && item.customId.endsWith("service"));
-        const confirmation = modal?.items?.find((item) => "customId" in item && item.customId.endsWith("confirm"));
-        expect(service).toMatchObject({
-            type: "string-select",
-            required: true,
-            options: [
-                expect.objectContaining({ value: "opaque-selection-reference-123" }),
-            ],
-        });
-        expect(confirmation).toMatchObject({
-            type: "string-select",
-            required: true,
-            options: [expect.objectContaining({ value: "remove_access" })],
-        });
-    });
-    it("revokes only for the acting user and returns an ephemeral advisory", async () => {
-        const revoke = vi.fn().mockResolvedValue({
-            provider: "twitch",
-            outcome: "completed",
-            providerRevocation: "failed",
-        });
-        const oauth = oauthService({ connections: [], revoke });
-        const replies = [];
-        const modal = createOAuthModule().interactions?.modals?.[0];
-        await modal?.execute(modalContext(oauth, {
-            reply: (response) => {
-                replies.push(response);
-                return Promise.resolve();
-            },
-        }));
-        expect(revoke).toHaveBeenCalledWith({
-            discordUserId: "12345678901234567",
-            selectionRef: "opaque-selection-reference-123",
-            confirmation: "remove_access",
-            comment: "No longer needed",
-            correlationId: "interaction-1",
-        });
-        expect(replies[0]).toMatchObject({ ephemeral: true });
-        expect(replies[0]?.componentsV2?.text?.[0]?.content).toContain("connected-app settings");
-    });
-});
-function oauthService(input) {
-    return {
-        connectionStatus: () => Promise.resolve([]),
-        listConnections: () => Promise.resolve(input.connections),
-        createAuthorization: () => Promise.resolve({
-            authorizationUrl: "https://example.com",
-            expiresAt: "",
-        }),
-        verifyEligibility: () => Promise.resolve({
-            provider: "youtube",
-            status: "unknown",
-            connected: false,
-            checkedAt: new Date().toISOString(),
-        }),
-        revoke: input.revoke ??
-            (() => Promise.resolve({
-                provider: "youtube",
-                outcome: "completed",
-                providerRevocation: "completed",
-            })),
-    };
-}
-function services(oauth) {
-    return {
-        has: (name) => name === HELYX_SERVICE_NAMES.oauth,
-        get: (name) => {
-            if (name !== HELYX_SERVICE_NAMES.oauth)
-                throw new Error("unknown service");
-            return oauth;
-        },
-    };
-}
-function commandContext(oauth, overrides = {}) {
-    return {
-        ...interactionBase(oauth),
-        showModal: () => Promise.resolve(),
-        getStringOption: () => null,
-        getBooleanOption: () => null,
-        getUserOption: () => null,
-        getChannelOption: () => null,
-        getRoleOption: () => null,
-        ...overrides,
-    };
-}
-function modalContext(oauth, overrides = {}) {
-    return {
-        ...interactionBase(oauth),
-        getField: (customId) => customId.endsWith("comment") ? "No longer needed" : "",
-        getStringSelectValues: (customId) => customId.endsWith("service")
-            ? ["opaque-selection-reference-123"]
-            : ["remove_access"],
-        getSelectedUserIds: () => [],
-        getSelectedRoleIds: () => [],
-        getSelectedMentionables: () => ({ userIds: [], roleIds: [] }),
-        getSelectedChannelIds: () => [],
-        ...overrides,
-    };
-}
-function interactionBase(oauth) {
-    return {
-        interactionId: "interaction-1",
-        userId: "12345678901234567",
-        userDisplayName: "Member",
-        userRoleIds: [],
-        isAdministrator: false,
-        serverId: "12345678901234568",
-        services: services(oauth),
-        reply: () => Promise.resolve(),
-        sendToChannel: () => Promise.resolve({ messageId: "message-1" }),
-        deleteChannelMessage: () => Promise.resolve(),
-        editChannelMessage: () => Promise.resolve(),
-        addChannelMessageReaction: () => Promise.resolve(),
-    };
-}
-//# sourceMappingURL=oauth-module.test.js.map