alvin-bot 4.13.1 → 4.13.2

package/CHANGELOG.md

@@ -2,6 +2,45 @@
 
 All notable changes to Alvin Bot are documented here.
 
+## [4.13.2] — 2026-04-16
+
+### ✨ Slack: `/alvin` slash commands + rewritten setup guide
+
+**Bug (carried over from v4.13.1):** Slash commands didn't work on Slack. When a user typed `/status` in a DM with the bot, Slack either hit its built-in `/status` (user status setter) or showed "Not a valid command" — nothing reached the bot. The Slack adapter only registered `message` + `app_mention` event handlers, no `command` handler; the manifest declared no slash commands.
+
+**Why it was a gotcha**: Slack treats slash commands as a separate event type (`command`), not as message text. Apps must explicitly register each command in their manifest AND add a `app.command(...)` handler to receive the events. None of this had been set up.
+
+**Fix**: v4.13.2 introduces a single namespaced command `/alvin` that takes a subcommand argument. Users type `/alvin status`, `/alvin new`, `/alvin effort high`, `/alvin help` — the Slack adapter parses the subcommand from `command.text` and forwards it as a `/status`/`/new`/etc. message through the existing `handlePlatformCommand` pipeline. Unknown subcommands fall through to normal LLM handling so `/alvin what's the weather` also works as a free-form query.
+
+### Technical details
+
+**New parser** `src/platforms/slack-slash-parser.ts`: pure `parseSlackSlashCommand(text)` helper. Empty text → `/help`. Single word → `/<word>`. Word + args → `/<word> <args>`. Lowercases subcommand, preserves arg capitalization, strips defensive leading slash, collapses extra whitespace. 8 unit tests.
+
+**Adapter change** `src/platforms/slack.ts`: new `app.command("/alvin", ...)` registration in `start()` (guarded with `typeof app.command === "function"` for test-mock compat). `ack()` fires immediately to meet Slack's 3-second requirement. New `handleSlashCommand(command)` method synthesizes an `IncomingMessage` with the translated `text` and the command's `channel_id`/`user_id` and forwards to the same `this.handler(...)` path as regular DMs. Response goes back via `chat.postMessage` (persistent, visible in channel history) rather than slash-command-native `respond()` (ephemeral) — matches DM behavior.
+
+**Slack app manifest**: requires a new `features.slash_commands` entry declaring `/alvin` and a new `commands` OAuth scope. Both are in the manifest JSON the setup guide pastes in — no manual per-field config. Existing installations need a one-time re-install to pick up the new `commands` scope (Slack shows a yellow banner after manifest save).
+
+**Setup guide rewrite** `src/web/setup-api.ts` Slack `setupSteps[]`: replaces the old 7-step "click-through every section" sequence with a 9-step manifest-paste flow that actually matches how the bot is currently set up (Messages Tab, Events, Socket Mode, slash commands — all covered in one JSON paste). Includes the full manifest JSON inline. New users get a working Slack app in ~2 minutes instead of hunting through the Slack API UI.
+
+### Testing
+
+- **Baseline**: 475 tests (v4.13.1)
+- **New**: `test/slack-slash-command.test.ts` — 8 tests (empty → /help, single word, args preservation, whitespace collapse, case insensitivity on subcommand, case preservation on args, defensive leading slash handling)
+- **Total**: 483 tests, all green, TSC clean
+- **Live smoke verification**: manifest pushed via Chrome browser automation, reinstall completed, Slack adapter re-registered with `app.command("/alvin")`. Live test of `/alvin status` pending user confirmation.
+
+### Files changed
+
+- **NEW**: `src/platforms/slack-slash-parser.ts`, `test/slack-slash-command.test.ts`
+- **Modified**: `src/platforms/slack.ts` (command registration + handler), `src/web/setup-api.ts` (slack setupSteps rewrite), `package.json` (4.13.1 → 4.13.2)
+
+### Known limitations
+
+- **One command namespace only**: we register `/alvin` not individual `/status`/`/new` etc. because `/status` conflicts with Slack's built-in command. Side effect: slightly more typing for users (`/alvin status` vs `/status`). Alternative namespaces considered (`/alvin-status` as multiple commands each) would work too but require more manifest boilerplate; deferred unless users complain.
+- **Channel responses are public**: when `/alvin status` is invoked in a channel, the bot's response is a normal `chat.postMessage` visible to the whole channel. If you want private responses there, use DM or switch the sendText call to use Slack's `response_url` (ephemeral). Deferred as enhancement — DM is the primary use case.
+
+---
+
 ## [4.13.1] — 2026-04-16
 
 ### 🐛 Patch: Slack Test Connection + PM2 → launchd migration for Maintenance UI

package/dist/platforms/slack-slash-parser.js

@@ -0,0 +1,32 @@
+/**
+ * v4.13.2 — Parse Slack `/alvin <subcommand> [args...]` slash command
+ * text into the platform-agnostic `/<subcommand> [args]` format that
+ * handlePlatformCommand already knows.
+ *
+ * Pure function — tested in isolation. Called from the Slack adapter's
+ * `app.command('/alvin')` handler.
+ *
+ * Rules:
+ *   - Empty text → `/help` (useful default, shows the commands list)
+ *   - Subcommand is lowercased for case-insensitive matching
+ *   - Args are kept verbatim (preserve user capitalization)
+ *   - A literal leading `/` on the subcommand is stripped defensively
+ *     (handles `/alvin /status` which becomes just `/status`, not `//status`)
+ */
+export function parseSlackSlashCommand(text) {
+    const trimmed = text.trim();
+    if (trimmed.length === 0)
+        return "/help";
+    // Split on first whitespace run — head is the subcommand, tail is args
+    const match = trimmed.match(/^(\S+)(?:\s+(.*))?$/);
+    if (!match)
+        return "/help";
+    let sub = (match[1] || "").toLowerCase();
+    // Strip a literal leading slash the user might have typed
+    if (sub.startsWith("/"))
+        sub = sub.slice(1);
+    if (sub.length === 0)
+        return "/help";
+    const args = (match[2] || "").trim();
+    return args ? `/${sub} ${args}` : `/${sub}`;
+}

package/dist/platforms/slack.js

@@ -17,6 +17,7 @@
  *   7. Set env vars and restart bot
  */
 import fs from "fs";
+import { parseSlackSlashCommand } from "./slack-slash-parser.js";
 let _slackState = {
     status: "disconnected",
     botName: null,
@@ -80,6 +81,31 @@ export class SlackAdapter {
             this.app.event("app_mention", async ({ event, say, client }) => {
                 await this.handleMention(event, say, client);
             });
+            // v4.13.2 — Handle the /alvin slash command.
+            //
+            // Slack sends slash commands as their own "command" event type
+            // (not as regular messages), so without this handler users who
+            // type /status see "Not a valid command" from Slack's built-in
+            // /status (which sets their user status). We register /alvin as
+            // a namespaced parent and parse the subcommand from command.text.
+            //
+            // CRITICAL: Slack requires ack() within 3 seconds or the user
+            // sees "/alvin didn't respond". We ack FIRST, then do the work
+            // asynchronously via the normal handler pipeline.
+            //
+            // Defensive: older/mocked Bolt versions might not expose .command().
+            // Skip registration silently rather than crashing start().
+            if (typeof this.app.command === "function") {
+                this.app.command("/alvin", async ({ command, ack }) => {
+                    await ack();
+                    try {
+                        await this.handleSlashCommand(command);
+                    }
+                    catch (err) {
+                        console.error("[slack] /alvin command failed:", err);
+                    }
+                });
+            }
             await this.app.start();
             _slackState.status = "connected";
             _slackState.connectedAt = Date.now();
@@ -160,6 +186,43 @@ export class SlackAdapter {
         };
         await this.handler(incoming);
     }
+    /**
+     * v4.13.2 — Handle /alvin slash command.
+     *
+     * Slack delivers these with command.text containing the part after
+     * "/alvin " (so "/alvin status" arrives with text="status"). We
+     * translate into a platform-agnostic "/<sub>[ args]" string and
+     * forward through the normal message handler — handlePlatformCommand
+     * picks it up since it starts with "/".
+     *
+     * The response goes back via the same sendText path as regular
+     * messages (chat.postMessage in command.channel_id). Slack allows
+     * this in addition to the slash-command-native respond() mechanism,
+     * and it keeps the codepath identical to message.im responses.
+     */
+    async handleSlashCommand(command) {
+        if (!this.handler)
+            return;
+        const translated = parseSlackSlashCommand(command.text || "");
+        const channelId = command.channel_id || "";
+        const userId = command.user_id || "";
+        const userName = command.user_name || userId;
+        const incoming = {
+            platform: "slack",
+            messageId: `cmd-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+            chatId: channelId,
+            userId,
+            userName,
+            text: translated,
+            // Slack slash commands are always issued 1:1 in the sense of
+            // "one user invoking". isGroup reflects the CHANNEL context
+            // (channel_name=directmessage is a DM, otherwise channel/group).
+            isGroup: command.channel_name && command.channel_name !== "directmessage",
+            isMention: false,
+            isReplyToBot: false,
+        };
+        await this.handler(incoming);
+    }
     async handleMention(event, _say, client) {
         if (!this.handler)
             return;

package/dist/web/setup-api.js

@@ -118,7 +118,7 @@ const PLATFORMS = [
         id: "slack",
         name: "Slack",
         icon: "💼",
-        description: "Slack workspace integration via Socket Mode (no public URL needed). DMs and @mentions in channels.",
+        description: "Slack workspace integration via Socket Mode (no public URL needed). DMs, @mentions in channels, and the `/alvin` slash command for /status, /new, /effort, /help (v4.13.2+).",
         envVars: [
             { key: "SLACK_BOT_TOKEN", label: "Bot Token (xoxb-...)", placeholder: "xoxb-...", secret: true },
             { key: "SLACK_APP_TOKEN", label: "App Token (xapp-...)", placeholder: "xapp-...", secret: true },
@@ -126,13 +126,15 @@ const PLATFORMS = [
         npmPackages: ["@slack/bolt"],
         setupUrl: "https://api.slack.com/apps",
         setupSteps: [
-            "Create a new App at api.slack.com/apps (From scratch)",
-            "Enable Socket Mode (Settings → Socket Mode → Enable)",
-            "Generate App-Level Token with 'connections:write' scope → copy as SLACK_APP_TOKEN",
-            "Go to OAuth & Permissions → add Bot Token Scopes: chat:write, channels:history, groups:history, im:history, mpim:history, app_mentions:read, files:write, reactions:write",
-            "Install App to Workspace → copy Bot User OAuth Token as SLACK_BOT_TOKEN",
-            "Subscribe to Events: message.im, message.groups, message.channels, app_mention",
-            "Invite the bot to channels with /invite @botname",
+            "Go to https://api.slack.com/apps and click 'Create New App' → 'From an app manifest'. Choose your workspace.",
+            "Paste the full manifest JSON below into the JSON tab (replaces the template). This sets scopes, events, Messages Tab, Socket Mode, and the /alvin slash command in one go:\n\n{\n  \"display_information\": { \"name\": \"Alvin\" },\n  \"features\": {\n    \"app_home\": {\n      \"home_tab_enabled\": false,\n      \"messages_tab_enabled\": true,\n      \"messages_tab_read_only_enabled\": false\n    },\n    \"bot_user\": { \"display_name\": \"Alvin\", \"always_online\": false },\n    \"slash_commands\": [\n      {\n        \"command\": \"/alvin\",\n        \"description\": \"Alvin bot commands\",\n        \"usage_hint\": \"new | status | effort low|medium|high|max | help\",\n        \"should_escape\": false\n      }\n    ]\n  },\n  \"oauth_config\": {\n    \"scopes\": {\n      \"bot\": [\n        \"app_mentions:read\", \"mpim:read\", \"chat:write\",\n        \"channels:history\", \"groups:history\", \"im:history\", \"mpim:history\",\n        \"files:write\", \"reactions:write\", \"files:read\",\n        \"commands\"\n      ]\n    },\n    \"pkce_enabled\": true\n  },\n  \"settings\": {\n    \"event_subscriptions\": {\n      \"bot_events\": [\n        \"app_mention\", \"message.channels\", \"message.groups\",\n        \"message.im\", \"message.mpim\"\n      ]\n    },\n    \"interactivity\": { \"is_enabled\": true },\n    \"org_deploy_enabled\": false,\n    \"socket_mode_enabled\": true,\n    \"token_rotation_enabled\": false\n  }\n}",
+            "Click Create. Slack creates the App with all the correct config pre-wired.",
+            "Go to Settings → Basic Information → App-Level Tokens → 'Generate Token and Scopes'. Name it 'socket', pick scope 'connections:write', click Generate. Copy the xapp-... token into SLACK_APP_TOKEN below.",
+            "Go to Settings → Install App → Install to Workspace → Allow. Copy the 'Bot User OAuth Token' (xoxb-...) into SLACK_BOT_TOKEN below.",
+            "Save both tokens here (click 'Save') and then click 'Test Connection' — you should see '@alvin on <Workspace>'.",
+            "Click 'Restart bot' in Maintenance → the Slack adapter connects automatically (look for '💬 Slack connected' in the logs).",
+            "In Slack: open the app in the sidebar, click 'Messages' tab, send a DM. Or use the slash command: /alvin status, /alvin new, /alvin effort high, /alvin help.",
+            "To use in channels: invite the bot with /invite @alvin and then @mention it (e.g. '@alvin what's the weather in Berlin?').",
         ],
     },
     {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "alvin-bot",
-  "version": "4.13.1",
+  "version": "4.13.2",
   "description": "Alvin Bot \u2014 Your personal AI agent on Telegram, WhatsApp, Discord, Signal, and Web.",
   "type": "module",
   "main": "dist/index.js",

package/test/slack-slash-command.test.ts

@@ -0,0 +1,61 @@
+/**
+ * v4.13.2 — Slack slash command parser tests.
+ *
+ * Users on Slack type `/alvin <subcommand> [args...]` which Bolt
+ * delivers via app.command('/alvin') with `command.text` containing
+ * the part after `/alvin `. We parse it into a platform-agnostic
+ * "/subcommand [args]" text that handlePlatformCommand already knows
+ * how to route (/new, /status, /effort, /help).
+ *
+ * Empty text → `/help` (most helpful default).
+ * Pass-through for everything else — unknown subcommand falls through
+ * to normal LLM prompt handling.
+ */
+import { describe, it, expect } from "vitest";
+import { parseSlackSlashCommand } from "../src/platforms/slack-slash-parser.js";
+
+describe("parseSlackSlashCommand (v4.13.2)", () => {
+  it("empty text maps to /help", () => {
+    expect(parseSlackSlashCommand("")).toBe("/help");
+    expect(parseSlackSlashCommand("   ")).toBe("/help");
+  });
+
+  it("single-word subcommand becomes /<subcommand>", () => {
+    expect(parseSlackSlashCommand("status")).toBe("/status");
+    expect(parseSlackSlashCommand("new")).toBe("/new");
+    expect(parseSlackSlashCommand("help")).toBe("/help");
+  });
+
+  it("subcommand with args preserves the args", () => {
+    expect(parseSlackSlashCommand("effort high")).toBe("/effort high");
+    expect(parseSlackSlashCommand("effort low")).toBe("/effort low");
+  });
+
+  it("multi-word args are preserved verbatim", () => {
+    expect(parseSlackSlashCommand("ask what is the weather in berlin")).toBe(
+      "/ask what is the weather in berlin",
+    );
+  });
+
+  it("collapses extra whitespace around subcommand", () => {
+    expect(parseSlackSlashCommand("   status   ")).toBe("/status");
+    expect(parseSlackSlashCommand("  effort    max   ")).toBe("/effort max");
+  });
+
+  it("lowercases the subcommand for case-insensitive matching", () => {
+    expect(parseSlackSlashCommand("Status")).toBe("/status");
+    expect(parseSlackSlashCommand("HELP")).toBe("/help");
+  });
+
+  it("does NOT lowercase the args (preserve user intent)", () => {
+    expect(parseSlackSlashCommand("ask What is THIS")).toBe(
+      "/ask What is THIS",
+    );
+  });
+
+  it("handles leading slash defensively — strips duplicate", () => {
+    // If a user literally types `/alvin /status`, Slack delivers text="/status"
+    expect(parseSlackSlashCommand("/status")).toBe("/status");
+    expect(parseSlackSlashCommand("/effort max")).toBe("/effort max");
+  });
+});