@gitterm/slack-bot 0.1.0

package/dist/cli.js

@@ -0,0 +1,602 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { BOT_ENV_HELP, cliOptions, hasRepository } from "@gitterm/bot";
+
+// src/index.ts
+import { createBot, withSavedConfig as loadSaved } from "@gitterm/bot";
+
+// src/adapter.ts
+import { downloadImage } from "@gitterm/bot";
+import {
+  App,
+  LogLevel,
+  webApi
+} from "@slack/bolt";
+
+// src/blocks.ts
+import { splitMessage, tablesToCode } from "@gitterm/bot";
+var ACTION = {
+  option: /^gitterm_option_\d+$/,
+  toggle: "gitterm_toggle",
+  submit: "gitterm_submit",
+  custom: "gitterm_custom",
+  permission: /^gitterm_permission_(once|always|reject)$/
+};
+var CUSTOM_MODAL = "gitterm_custom_modal";
+var CUSTOM_INPUT = "gitterm_custom_text";
+var BLOCK_PREFIX = "gitterm";
+var BUTTONS_PER_ROW = 5;
+var CHECKBOX_LIMIT = 10;
+var LABEL_LIMIT = 75;
+var SECTION_LIMIT = 2900;
+var SECTIONS_PER_MESSAGE = 10;
+var OPEN_COLOR = "#E8A33D";
+var SETTLED_COLOR = "#B8BFC7";
+var truncate = (value, limit) => value.length > limit ? `${value.slice(0, limit - 1)}…` : value;
+var plain = (text, limit = LABEL_LIMIT) => ({
+  type: "plain_text",
+  text: truncate(text, limit)
+});
+var context = (text) => ({
+  type: "context",
+  elements: [{ type: "mrkdwn", text }]
+});
+var section = (text) => ({ type: "section", text: { type: "mrkdwn", text } });
+var blockId = (promptId, row = 0) => `${BLOCK_PREFIX}|${promptId}|${row}`;
+var promptIdOf = (id) => {
+  const [prefix, promptId] = id.split("|");
+  return prefix === BLOCK_PREFIX && promptId ? promptId : null;
+};
+function toMrkdwn(markdown) {
+  let inCode = false;
+  return markdown.split(`
+`).map((line) => {
+    if (line.trimStart().startsWith("```")) {
+      inCode = !inCode;
+      return line;
+    }
+    if (inCode)
+      return line;
+    return line.replace(/^#{1,6}\s+(.+)$/, "*$1*").replace(/\*\*(.+?)\*\*/g, "*$1*").replace(/~~(.+?)~~/g, "~$1~").replace(/\[([^\]]+)]\((https?:\/\/[^)]+)\)/g, "<$2|$1>");
+  }).join(`
+`);
+}
+function answerMessages(markdown, footer) {
+  const quiet = markdown.replace(/<!(channel|here|everyone)[^>]*>/g, "@$1");
+  const sections = splitMessage(toMrkdwn(tablesToCode(quiet)), SECTION_LIMIT);
+  const messages = [];
+  for (let index = 0;index < sections.length; index += SECTIONS_PER_MESSAGE) {
+    const group = sections.slice(index, index + SECTIONS_PER_MESSAGE);
+    const last = index + SECTIONS_PER_MESSAGE >= sections.length;
+    messages.push({
+      text: group.join(`
+
+`),
+      blocks: [...group.map(section), ...last ? [{ type: "divider" }, context(footer)] : []]
+    });
+  }
+  return messages;
+}
+function leadIn(prompt, mention) {
+  const who = mention ? ` for <@${prompt.requester.id}>` : "";
+  if (prompt.kind === "permission")
+    return context(`*Approval needed${who}*`);
+  const counter = prompt.total > 1 ? `Question ${prompt.index + 1} of ${prompt.total}` : "Question";
+  return context(`*${counter}${who}* · ${prompt.question.header}`);
+}
+function body(prompt) {
+  if (prompt.kind === "permission") {
+    const { request } = prompt;
+    const patterns = request.patterns.filter(Boolean);
+    return [
+      section(`The agent wants to run *${request.title}*`),
+      ...patterns.length ? [section(`\`\`\`${patterns.join(`
+`).slice(0, 2800)}\`\`\``)] : []
+    ];
+  }
+  const { question } = prompt;
+  const options = question.options.map((option, i) => `${i + 1}. *${option.label}*${option.description ? ` — ${option.description}` : ""}`).join(`
+`);
+  return [section(`*${question.question}*`), ...options ? [section(options)] : []];
+}
+var customButton = {
+  type: "button",
+  action_id: ACTION.custom,
+  text: plain("Write your own answer"),
+  value: "custom"
+};
+function controls(prompt) {
+  if (prompt.kind === "permission") {
+    return [
+      {
+        type: "actions",
+        block_id: blockId(prompt.id),
+        elements: [
+          { label: "Allow once", value: "once", style: "primary" },
+          { label: "Always allow", value: "always" },
+          { label: "Deny", value: "reject", style: "danger" }
+        ].map((button) => ({
+          type: "button",
+          action_id: `gitterm_permission_${button.value}`,
+          text: plain(button.label),
+          value: button.value,
+          ...button.style ? { style: button.style } : {}
+        }))
+      },
+      context("Or reply *yes*, *always*, or *no* in this thread.")
+    ];
+  }
+  const { question } = prompt;
+  const rows = [];
+  if (question.multiple && question.options.length > 0) {
+    rows.push({
+      type: "actions",
+      block_id: blockId(prompt.id),
+      elements: [
+        {
+          type: "checkboxes",
+          action_id: ACTION.toggle,
+          options: question.options.slice(0, CHECKBOX_LIMIT).map((option, i) => ({
+            text: plain(option.label),
+            ...option.description ? { description: plain(option.description) } : {},
+            value: String(i)
+          }))
+        },
+        {
+          type: "button",
+          action_id: ACTION.submit,
+          style: "primary",
+          text: plain("Submit"),
+          value: "submit"
+        },
+        ...question.custom ? [customButton] : []
+      ]
+    });
+  } else {
+    for (let start = 0;start < question.options.length; start += BUTTONS_PER_ROW) {
+      rows.push({
+        type: "actions",
+        block_id: blockId(prompt.id, rows.length),
+        elements: question.options.slice(start, start + BUTTONS_PER_ROW).map((option, i) => ({
+          type: "button",
+          action_id: `gitterm_option_${start + i}`,
+          text: plain(option.label),
+          value: String(start + i)
+        }))
+      });
+    }
+    if (question.custom) {
+      rows.push({
+        type: "actions",
+        block_id: blockId(prompt.id, rows.length),
+        elements: [customButton]
+      });
+    }
+  }
+  const hint = question.options.length > 0 ? question.multiple ? "Tick options and press *Submit*, or reply with their numbers (e.g. `1, 3`)." : "Press a button or reply with its number." : "Reply in this thread with your answer.";
+  return [...rows, context(hint)];
+}
+function promptAttachment(prompt) {
+  const fallback = prompt.kind === "permission" ? `<@${prompt.requester.id}> the agent needs approval: ${prompt.request.title}` : `<@${prompt.requester.id}> the agent has a question: ${prompt.question.header}`;
+  return {
+    color: OPEN_COLOR,
+    fallback,
+    blocks: [leadIn(prompt, true), ...body(prompt), ...controls(prompt)]
+  };
+}
+function settledAttachment(prompt, outcome) {
+  return {
+    color: SETTLED_COLOR,
+    fallback: outcome,
+    blocks: [leadIn(prompt, false), ...body(prompt), context(outcome)]
+  };
+}
+function customAnswerView(prompt) {
+  return {
+    type: "modal",
+    callback_id: CUSTOM_MODAL,
+    private_metadata: prompt.id,
+    title: plain(prompt.question.header || "Your answer", 24),
+    submit: plain("Send to the agent"),
+    close: plain("Cancel"),
+    blocks: [
+      section(prompt.question.question),
+      {
+        type: "input",
+        block_id: "answer",
+        label: plain("Your answer"),
+        element: { type: "plain_text_input", action_id: CUSTOM_INPUT, multiline: true }
+      }
+    ]
+  };
+}
+
+// src/adapter.ts
+var HISTORY_LIMIT = 200;
+function required(value, name) {
+  if (!value?.trim())
+    throw new Error(`${name} is required`);
+  return value.trim();
+}
+function createSlackAdapter(options = {}) {
+  const botToken = required(options.botToken ?? options.app?.client.token ?? process.env.SLACK_BOT_TOKEN, "SLACK_BOT_TOKEN");
+  const owned = !options.app;
+  const app = options.app ?? new App({
+    token: botToken,
+    appToken: required(options.appToken ?? process.env.SLACK_APP_TOKEN, "SLACK_APP_TOKEN"),
+    socketMode: true,
+    logLevel: LogLevel.WARN
+  });
+  const client = owned ? app.client : new webApi.WebClient(botToken);
+  const users = new Map;
+  const ticked = new Map;
+  let indicatorAvailable = true;
+  let teamId = "";
+  let botUserId = "";
+  const stripMention = (text) => text.replaceAll(`<@${botUserId}>`, "").trim();
+  const user = async (id) => {
+    if (!id)
+      return { id: "unknown", name: "someone", guest: true };
+    const cached = users.get(id);
+    if (cached && Date.now() - cached.at < 60000)
+      return cached.user;
+    const known = await client.users.info({ user: id }).then(({ user: profile }) => ({
+      id,
+      name: profile?.profile?.display_name || profile?.real_name || profile?.name || id,
+      guest: Boolean(!profile || profile.deleted || profile?.is_restricted || profile?.is_ultra_restricted || profile?.team_id && teamId && profile.team_id !== teamId)
+    })).catch(() => ({ id, name: id, guest: true }));
+    users.delete(id);
+    users.set(id, { user: known, at: Date.now() });
+    if (users.size > 2000)
+      users.delete(users.keys().next().value);
+    return known;
+  };
+  const file = (entry) => ({
+    id: entry.id,
+    name: entry.name ?? entry.id,
+    mime: entry.mimetype ?? "application/octet-stream",
+    size: entry.size ?? -1,
+    async download(signal) {
+      return downloadImage(entry.url_private_download ?? "", {
+        hosts: ["files.slack.com", "files-pri.slack.com"],
+        signal,
+        headers: { Authorization: `Bearer ${botToken}` }
+      }).catch((error) => {
+        throw new Error(`Could not download “${entry.name ?? entry.id}” from Slack; the app needs the files:read scope (${error instanceof Error ? error.message : error})`);
+      });
+    }
+  });
+  const fromBot = (message) => Boolean(message.bot_id) || message.subtype === "bot_message" || message.user === botUserId;
+  return {
+    platform: "slack",
+    displayName: "Slack",
+    async start(events) {
+      const sameTeam = (id) => !id || id === teamId;
+      app.event("app_mention", async ({ event, context }) => {
+        if (!sameTeam(context.teamId) || event.bot_id || !event.user)
+          return;
+        if (event.channel.startsWith("D"))
+          return;
+        events.message({
+          id: event.ts,
+          thread: { channel: event.channel, thread: event.thread_ts ?? event.ts },
+          author: await user(event.user),
+          text: stripMention(event.text),
+          files: (event.files ?? []).map(file),
+          mentioned: true,
+          inThread: Boolean(event.thread_ts)
+        });
+      });
+      app.message(async ({ message, context }) => {
+        const reply = message;
+        if (!sameTeam(context.teamId) || fromBot(reply) || !reply.user || !reply.ts)
+          return;
+        if (reply.subtype && reply.subtype !== "file_share")
+          return;
+        if (reply.channel_type === "im") {
+          events.message({
+            id: reply.ts,
+            thread: { channel: reply.channel, thread: reply.thread_ts ?? reply.ts },
+            author: await user(reply.user),
+            text: stripMention(reply.text ?? ""),
+            files: (reply.files ?? []).map(file),
+            mentioned: true,
+            inThread: Boolean(reply.thread_ts),
+            direct: true
+          });
+          return;
+        }
+        if (!reply.thread_ts || reply.thread_ts === reply.ts)
+          return;
+        if (reply.text?.includes(`<@${botUserId}>`))
+          return;
+        events.message({
+          id: reply.ts,
+          thread: { channel: reply.channel, thread: reply.thread_ts },
+          author: await user(reply.user),
+          text: reply.text?.trim() ?? "",
+          files: (reply.files ?? []).map(file),
+          mentioned: false,
+          inThread: true
+        });
+      });
+      const answer = async (body, promptId, value) => promptId === null ? "stale" : events.answer(promptId, value, await user(body.user.id));
+      const notice = (text) => ({
+        response_type: "ephemeral",
+        replace_original: false,
+        text
+      });
+      const stale = notice("This was already answered.");
+      const outcomeNotice = (outcome) => outcome === "forbidden" ? notice("Only people allowed to use this bot can answer.") : outcome === "stale" ? stale : undefined;
+      app.action(ACTION.option, async ({ ack, body, action, respond }) => {
+        await ack();
+        const promptId = promptIdOf(action.block_id);
+        const prompt = promptId ? events.prompt(promptId) : undefined;
+        const label = prompt?.kind === "question" ? prompt.question.options[Number(action.value)]?.label : undefined;
+        const reply = label ? outcomeNotice(await answer(body, promptId, { kind: "question", labels: [label] })) : stale;
+        if (reply)
+          await respond(reply);
+      });
+      app.action(ACTION.toggle, async ({ ack, action, body }) => {
+        await ack();
+        const promptId = promptIdOf(action.block_id);
+        if (promptId && events.canAnswer && !events.canAnswer(promptId, await user(body.user.id)))
+          return;
+        if (promptId)
+          ticked.set(promptId, action.selected_options.map((option) => Number(option.value)));
+      });
+      app.action(ACTION.submit, async ({ ack, body, action, respond }) => {
+        await ack();
+        const promptId = promptIdOf(action.block_id);
+        const prompt = promptId ? events.prompt(promptId) : undefined;
+        if (prompt?.kind !== "question" || !promptId) {
+          await respond(stale);
+          return;
+        }
+        const labels = (ticked.get(promptId) ?? []).map((index) => prompt.question.options[index]?.label).filter((label) => Boolean(label));
+        if (labels.length === 0) {
+          await respond({ ...stale, text: "Tick at least one option before pressing Submit." });
+          return;
+        }
+        const reply = outcomeNotice(await answer(body, promptId, { kind: "question", labels }));
+        if (reply)
+          await respond(reply);
+      });
+      app.action(ACTION.permission, async ({ ack, body, action, respond }) => {
+        await ack();
+        const response = action.value;
+        const reply = outcomeNotice(await answer(body, promptIdOf(action.block_id), { kind: "permission", response }));
+        if (reply)
+          await respond(reply);
+      });
+      app.action(ACTION.custom, async ({ ack, body, action, client: web, respond }) => {
+        await ack();
+        const promptId = promptIdOf(action.block_id);
+        const prompt = promptId ? events.prompt(promptId) : undefined;
+        if (prompt?.kind !== "question") {
+          await respond(stale);
+          return;
+        }
+        await web.views.open({ trigger_id: body.trigger_id, view: customAnswerView(prompt) });
+      });
+      app.view(CUSTOM_MODAL, async ({ ack, body, view }) => {
+        const promptId = view.private_metadata;
+        const prompt = events.prompt(promptId);
+        const text = view.state.values.answer?.[CUSTOM_INPUT]?.value?.trim() ?? "";
+        const labels = prompt?.kind === "question" && prompt.question.multiple ? (ticked.get(promptId) ?? []).map((index) => prompt.question.options[index]?.label ?? "") : [];
+        const outcome = text ? events.answer(promptId, { kind: "question", labels: [...new Set([...labels.filter(Boolean), text])] }, await user(body.user.id)) : "empty";
+        if (outcome === "answered")
+          return ack();
+        await ack({
+          response_action: "errors",
+          errors: {
+            answer: outcome === "empty" ? "Write an answer first." : outcome === "forbidden" ? "Only people allowed to use this bot can answer." : "This question was already answered."
+          }
+        });
+      });
+      if (owned) {
+        app.error(async (error) => {
+          console.error("Slack error", error);
+        });
+        await app.start();
+      }
+      const identity = await client.auth.test();
+      teamId = identity.team_id ?? "";
+      botUserId = identity.user_id ?? "";
+      return { scope: teamId };
+    },
+    async stop() {
+      if (owned)
+        await app.stop();
+    },
+    async history(thread, after) {
+      const messages = [];
+      let cursor;
+      for (let page = 0;page < 5; page++) {
+        const replies = await client.conversations.replies({
+          channel: thread.channel,
+          ts: thread.thread,
+          limit: HISTORY_LIMIT,
+          ...after ? { oldest: after, inclusive: false } : {},
+          ...cursor ? { cursor } : {}
+        });
+        messages.push(...replies.messages ?? []);
+        cursor = replies.response_metadata?.next_cursor?.trim();
+        if (!cursor)
+          break;
+      }
+      const result = [];
+      for (const message of messages) {
+        if (!message.ts || after && Number(message.ts) <= Number(after))
+          continue;
+        const bot = fromBot(message);
+        result.push({
+          id: message.ts,
+          author: bot ? { id: message.user ?? "bot", name: "assistant" } : await user(message.user),
+          fromBot: bot,
+          text: stripMention(message.text ?? ""),
+          files: (message.files ?? []).map(file)
+        });
+      }
+      return result;
+    },
+    async post(thread, text) {
+      const posted = await client.chat.postMessage({
+        channel: thread.channel,
+        thread_ts: thread.thread,
+        text
+      });
+      if (!posted.ts)
+        throw new Error("Slack did not return a message timestamp");
+      return posted.ts;
+    },
+    async edit(thread, messageId, text) {
+      await client.chat.update({ channel: thread.channel, ts: messageId, text });
+    },
+    async remove(thread, messageId) {
+      await client.chat.delete({ channel: thread.channel, ts: messageId });
+    },
+    async reply(thread, markdown, footer, delivery) {
+      const messages = answerMessages(markdown, footer);
+      for (let index = delivery?.sent ?? 0;index < messages.length; index++) {
+        await client.chat.postMessage({
+          channel: thread.channel,
+          thread_ts: thread.thread,
+          ...messages[index]
+        });
+        await delivery?.recordSent(index + 1);
+      }
+    },
+    async ask(thread, prompt) {
+      const posted = await client.chat.postMessage({
+        channel: thread.channel,
+        thread_ts: thread.thread,
+        attachments: [promptAttachment(prompt)]
+      });
+      if (!posted.ts)
+        throw new Error("Slack did not return a message timestamp");
+      return posted.ts;
+    },
+    async settle(thread, messageId, prompt, outcome) {
+      ticked.delete(prompt.id);
+      await client.chat.update({
+        channel: thread.channel,
+        ts: messageId,
+        text: "",
+        attachments: [settledAttachment(prompt, outcome)]
+      });
+    },
+    async indicate(thread, status) {
+      if (!indicatorAvailable)
+        return false;
+      try {
+        await client.assistant.threads.setStatus({
+          channel_id: thread.channel,
+          thread_ts: thread.thread,
+          status
+        });
+        return true;
+      } catch (error) {
+        if (error.code === "slack_webapi_platform_error") {
+          indicatorAvailable = false;
+          console.warn("Slack refused the native status indicator; using status messages instead", error);
+        }
+        return false;
+      }
+    },
+    async mark(message, state) {
+      await client.reactions.add({
+        channel: message.thread.channel,
+        timestamp: message.id,
+        name: { seen: "eyes", done: "white_check_mark", failed: "x" }[state]
+      });
+    }
+  };
+}
+// src/manifest.ts
+function slackManifest(name = "GitTerm Agent") {
+  return {
+    display_information: {
+      name,
+      description: "A coding agent for your repository, running in a GitTerm sandbox"
+    },
+    features: {
+      bot_user: { display_name: name, always_online: true },
+      app_home: {
+        home_tab_enabled: false,
+        messages_tab_enabled: true,
+        messages_tab_read_only_enabled: false
+      }
+    },
+    oauth_config: {
+      scopes: {
+        bot: [
+          "app_mentions:read",
+          "channels:history",
+          "groups:history",
+          "im:history",
+          "chat:write",
+          "files:read",
+          "reactions:write",
+          "users:read"
+        ]
+      }
+    },
+    settings: {
+      event_subscriptions: {
+        bot_events: ["app_mention", "message.channels", "message.groups", "message.im"]
+      },
+      interactivity: { is_enabled: true },
+      org_deploy_enabled: false,
+      socket_mode_enabled: true,
+      token_rotation_enabled: false
+    }
+  };
+}
+
+// src/index.ts
+function createSlackBot(options) {
+  const { botToken, appToken, app, ...bot } = options;
+  return createBot({
+    ...bot,
+    adapter: createSlackAdapter({
+      ...botToken ? { botToken } : {},
+      ...appToken ? { appToken } : {},
+      ...app ? { app } : {}
+    })
+  });
+}
+async function withSavedConfig(options = {}) {
+  return { ...options, ...await loadSaved(options, "slack", options.logger) };
+}
+
+// src/cli.ts
+var USAGE = `Usage: gitterm-slack-bot [-h] [--repo <url>[#branch]] [--model <provider/model>]
+                    [--instructions-file <path>]
+       gitterm-slack-bot manifest [name]
+
+Environment (a .env file in the working directory is loaded):
+  SLACK_BOT_TOKEN                 Bot token (xoxb-…)
+  SLACK_APP_TOKEN                 App-level token with connections:write (xapp-…)
+${BOT_ENV_HELP}`;
+var { command, options: local } = cliOptions();
+if (command === "manifest") {
+  console.log(JSON.stringify(slackManifest(process.argv[3]), null, 2));
+} else if (command === "help" || !hasRepository(local) && !process.env.GITTERM_API_TOKEN) {
+  console.log(USAGE);
+  process.exitCode = command === "help" ? 0 : 1;
+} else {
+  const options = await withSavedConfig(local);
+  if (!hasRepository(options)) {
+    console.log(USAGE);
+    console.error(`
+No repository: set GITTERM_BOT_REPO, or save this bot under Bots in GitTerm.`);
+    process.exit(1);
+  }
+  const bot = createSlackBot(options);
+  await bot.start();
+  const shutdown = () => void bot.stop().finally(() => process.exit(0));
+  process.once("SIGINT", shutdown);
+  process.once("SIGTERM", shutdown);
+}

package/dist/index.d.ts

@@ -0,0 +1,22 @@
+import { type Bot, type BotOptions } from "@gitterm/bot";
+import { type SlackAdapterOptions } from "./adapter.js";
+export { createSlackAdapter, type SlackAdapterOptions } from "./adapter.js";
+export { slackManifest } from "./manifest.js";
+export type { Bot, RepoTarget, WorkspaceOverrides } from "@gitterm/bot";
+export type SlackBotOptions = Omit<BotOptions, "adapter"> & SlackAdapterOptions;
+/**
+ * A Slack bot that runs a coding agent on your repository in a GitTerm sandbox.
+ *
+ * ```ts
+ * await createSlackBot({ repo: "https://github.com/acme/app" }).start();
+ * ```
+ *
+ * Tokens default to `SLACK_BOT_TOKEN`, `SLACK_APP_TOKEN`, and `GITTERM_API_TOKEN`; pass `app` to
+ * add the agent to a Bolt app you already run.
+ */
+export declare function createSlackBot(options: SlackBotOptions): Bot;
+/**
+ * Adds the settings saved for this bot under Bots in the GitTerm dashboard, found by its API
+ * token. Anything you pass wins: `createSlackBot(await withSavedConfig({ ... }))`.
+ */
+export declare function withSavedConfig(options?: SlackBotOptions): Promise<SlackBotOptions>;