roger-roger 0.1.0

package/skills/roger-roger/scripts/sessions.mjs

@@ -0,0 +1,218 @@
+// The register of agent sessions: who is running, what to call them, and what is waiting for them.
+//
+// Every CLI call carries a session id worked out by agent.mjs, so the separate processes one agent
+// spawns are recognisably the same session, whatever agent it is. On first sight a session is given
+// a colour nickname — sage, rose, plum — which is how the user sees it in Slack and how they address
+// it in a message.
+//
+// Kept in ~/.roger-roger/sessions.json. The daemon is the only writer while it runs.
+
+import fs from "node:fs";
+import path from "node:path";
+import { rogerRogerHome, pidAlive } from "./lib.mjs";
+import { NAMES, colourOf, pickName } from "./names.mjs";
+
+// Without an agent pid to check, a session counts as gone once it has been quiet this long.
+const QUIET_MS = 30 * 60 * 1000;
+// Even with a live pid, a session that hasn't said anything all day is no longer a sensible target.
+const MAX_IDLE_MS = 12 * 3600 * 1000;
+const FORGET_MS = 7 * 24 * 3600 * 1000;
+const MAX_QUEUE = 50;
+
+export const STATES = ["working", "waiting", "paused", "done"];
+
+function file() {
+  return path.join(rogerRogerHome(), "sessions.json");
+}
+
+export function load() {
+  try {
+    const raw = JSON.parse(fs.readFileSync(file(), "utf8"));
+    return { sessions: raw.sessions ?? {}, threads: raw.threads ?? {}, aliases: raw.aliases ?? {} };
+  } catch {
+    return { sessions: {}, threads: {}, aliases: {} };
+  }
+}
+
+export function save(state) {
+  fs.mkdirSync(path.dirname(file()), { recursive: true });
+  const tmp = `${file()}.${process.pid}.tmp`;
+  fs.writeFileSync(tmp, JSON.stringify(state, null, 2) + "\n", "utf8");
+  fs.renameSync(tmp, file());
+}
+
+function update(fn) {
+  const state = load();
+  const result = fn(state);
+  save(prune(state));
+  return result;
+}
+
+/** Drop sessions nobody has heard from in a week, and thread bindings whose session went with them. */
+function prune(state, now = Date.now()) {
+  for (const [id, s] of Object.entries(state.sessions)) {
+    if (now - Date.parse(s.lastSeen ?? 0) > FORGET_MS) delete state.sessions[id];
+  }
+  for (const [ts, id] of Object.entries(state.threads)) {
+    if (!state.sessions[id]) delete state.threads[ts];
+  }
+  for (const [fingerprint, id] of Object.entries(state.aliases ?? {})) {
+    if (!state.sessions[id]) delete state.aliases[fingerprint];
+  }
+  return state;
+}
+
+/** Is this session still someone an agent could be listening on? */
+export function isLive(session, now = Date.now()) {
+  if (!session || session.endedAt) return false;
+  const idle = now - Date.parse(session.lastSeen ?? 0);
+  if (idle > MAX_IDLE_MS) return false;
+  return session.pid ? pidAlive(session.pid) : idle < QUIET_MS;
+}
+
+/**
+ * Record that a session is active now, giving it a nickname the first time it is seen. `identity`
+ * comes from the CLI (id, pid, cwd, project, host); `about` is what the agent told us about itself
+ * (--session name, model, agent). Returns the session.
+ */
+export function register(identity, about = {}, pool = NAMES) {
+  return update((state) => {
+    const now = new Date().toISOString();
+    state.aliases ??= {};
+    // An agent that publishes nothing is recognised by its terminal: once a command from it has
+    // said which session it belongs to, later commands that leave `--session` off still land there.
+    const fingerprint = identity.fingerprint ?? "";
+    const id = identity.source === "terminal" && state.aliases[fingerprint]
+      ? state.aliases[fingerprint]
+      : identity.id;
+    if (fingerprint) state.aliases[fingerprint] = id;
+    const existing = state.sessions[id];
+    const taken = Object.values(state.sessions)
+      .filter((s) => s.id !== id && isLive(s))
+      .map((s) => s.nickname);
+    const session = {
+      ...existing,
+      id,
+      // A session keeps its name, unless someone else was given it while this one was quiet — two
+      // live agents answering to "jade" is exactly what the names are there to prevent.
+      nickname: existing?.nickname && !taken.includes(existing.nickname) ? existing.nickname : pickName(taken, pool),
+      pid: identity.pid || existing?.pid || 0,
+      cwd: identity.cwd ?? existing?.cwd ?? "",
+      project: identity.project || existing?.project || "",
+      host: identity.host ?? existing?.host ?? "",
+      attended: identity.attended ?? existing?.attended ?? false,
+      // The Herdr pane it runs in, and what its tab and agent were last labelled (herdr.mjs).
+      herdr: identity.herdr ?? existing?.herdr ?? null,
+      herdrLabel: existing?.herdrLabel ?? null,
+      name: about.name ?? existing?.name ?? "",
+      model: about.model ?? existing?.model ?? "",
+      agent: about.agent || existing?.agent || identity.agent || "",
+      source: identity.source ?? existing?.source ?? "",
+      state: about.state ?? existing?.state ?? "working",
+      firstSeen: existing?.firstSeen ?? now,
+      lastSeen: now,
+      queue: existing?.queue ?? [],
+      endedAt: null,
+    };
+    state.sessions[id] = session;
+    return session;
+  });
+}
+
+export function get(id) {
+  return load().sessions[id] ?? null;
+}
+
+export function byNickname(nickname) {
+  const want = String(nickname ?? "").toLowerCase();
+  return Object.values(load().sessions).find((s) => s.nickname === want) ?? null;
+}
+
+/** Every live session, oldest first, with its colour resolved. */
+export function live(now = Date.now()) {
+  return Object.values(load().sessions)
+    .filter((s) => isLive(s, now))
+    .sort((a, b) => Date.parse(a.firstSeen) - Date.parse(b.firstSeen))
+    .map(decorate);
+}
+
+export function all() {
+  return Object.values(load().sessions)
+    .sort((a, b) => Date.parse(b.lastSeen) - Date.parse(a.lastSeen))
+    .map(decorate);
+}
+
+/** A session as the rest of the code wants it: with its colour, swatch and live flag. */
+export function decorate(session, now = Date.now()) {
+  const colour = colourOf(session.nickname);
+  return { ...session, colour: colour.hex, swatch: colour.swatch, live: isLive(session, now) };
+}
+
+export function touch(id, patch = {}) {
+  return update((state) => {
+    const session = state.sessions[id];
+    if (!session) return null;
+    Object.assign(session, patch, { lastSeen: new Date().toISOString() });
+    return session;
+  });
+}
+
+/** The agent says it is finished; it stops being a routing target straight away. */
+export function end(id) {
+  return update((state) => {
+    const session = state.sessions[id];
+    if (!session) return null;
+    session.endedAt = new Date().toISOString();
+    session.state = "done";
+    return session;
+  });
+}
+
+/** Give a session a different nickname (`sessions rename sage plum`). */
+export function rename(id, nickname) {
+  return update((state) => {
+    const session = state.sessions[id];
+    if (!session) return null;
+    const clash = Object.values(state.sessions).find((s) => s.id !== id && s.nickname === nickname && isLive(s));
+    if (clash) throw new Error(`"${nickname}" is already taken by another running session`);
+    session.nickname = nickname;
+    return session;
+  });
+}
+
+/** Remember that a Slack thread belongs to a session, so replies in it need no picker. */
+export function bindThread(ts, sessionId) {
+  if (!ts || !sessionId) return;
+  update((state) => {
+    state.threads[ts] = sessionId;
+  });
+}
+
+export function threads() {
+  return load().threads;
+}
+
+/** Hand a message to a session. It waits there until the agent next checks in. */
+export function enqueue(id, message) {
+  return update((state) => {
+    const session = state.sessions[id];
+    if (!session) return null;
+    session.queue = [...(session.queue ?? []), message].slice(-MAX_QUEUE);
+    return session;
+  });
+}
+
+/** Everything waiting for a session, removed as it is handed over. */
+export function drain(id) {
+  return update((state) => {
+    const session = state.sessions[id];
+    if (!session?.queue?.length) return [];
+    const queue = session.queue;
+    session.queue = [];
+    return queue;
+  });
+}
+
+export function pending(id) {
+  return get(id)?.queue ?? [];
+}

package/skills/roger-roger/scripts/slack.mjs

@@ -0,0 +1,240 @@
+// Slack Web API calls and a minimal Socket Mode client (Node's built-in WebSocket).
+
+import fs from "node:fs";
+import path from "node:path";
+import { isUserId, slackAppToken, slackToken } from "./lib.mjs";
+
+/**
+ * Blocks, optionally wrapped in an attachment so Slack draws a coloured bar down the left edge.
+ * That bar is a session's colour, which is what makes three agents in one DM tellable apart at a
+ * glance. Both keys are always sent, so an update can add or remove the bar.
+ *
+ * With an attachment, `text` becomes the attachment's `fallback` rather than the message's own
+ * text: Slack renders a top-level `text` *as well as* the attachment, which showed every coloured
+ * message twice. As a fallback it is still what a notification and an unsupported client show.
+ */
+export function messageBody({ text, blocks, color }) {
+  return color
+    ? { text: "", blocks: [], attachments: [{ color, fallback: text, blocks }] }
+    : { text, blocks, attachments: [] };
+}
+
+/** Where the Slack API lives. Overridable so a test can stand one up and watch what we send. */
+export const apiBase = () => (process.env.ROGER_ROGER_SLACK_API || "https://slack.com/api").replace(/\/$/, "");
+
+export async function slackCall(method, token, payload) {
+  const res = await fetch(`${apiBase()}/${method}`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json; charset=utf-8", Authorization: `Bearer ${token}` },
+    body: JSON.stringify(payload),
+    signal: AbortSignal.timeout(15_000),
+  });
+  return res.json().catch(() => ({ ok: false, error: `http_${res.status}` }));
+}
+
+function botToken() {
+  const token = slackToken();
+  if (!token) throw new Error("SLACK_API_BOT_TOKEN is not set");
+  return token;
+}
+
+/** Post to the configured target. Returns the real channel ID and message ts. */
+export async function postMessage(config, { text, blocks, color, thread_ts }) {
+  const token = botToken();
+  const target = config.slack.target;
+  if (!target) throw new Error("no Slack target configured");
+
+  const payload = { ...messageBody({ text, blocks, color }), ...(thread_ts ? { thread_ts } : {}), unfurl_links: false, unfurl_media: false };
+  let r = await slackCall("chat.postMessage", token, { ...payload, channel: target });
+  // Some workspaces only allow DMs to a user through an opened conversation.
+  if (!r.ok && isUserId(target) && ["channel_not_found", "not_in_channel"].includes(r.error)) {
+    const open = await slackCall("conversations.open", token, { users: target });
+    if (open.ok) r = await slackCall("chat.postMessage", token, { ...payload, channel: open.channel.id });
+  }
+  if (!r.ok) throw new Error(`Slack: ${r.error}`);
+  return { channel: r.channel, ts: r.ts };
+}
+
+export async function updateMessage(channel, ts, { text, blocks, color }) {
+  const r = await slackCall("chat.update", botToken(), { channel, ts, ...messageBody({ text, blocks, color }) });
+  if (!r.ok) throw Object.assign(new Error(`Slack: ${r.error}`), { code: r.error });
+}
+
+const MAX_FILE_BYTES = 25 * 1024 * 1024;
+
+/** A file name that is safe on every platform, and unique per Slack file. */
+function safeFileName(file) {
+  const name = String(file.name ?? file.title ?? "file").replace(/[^\w.-]+/g, "_").slice(-80);
+  return `${file.id ?? "file"}-${name || "file"}`;
+}
+
+/**
+ * Save a file the user shared, and return where it landed. Slack's private URLs want the bot token
+ * and the `files:read` scope; without the scope Slack answers with its sign-in page rather than an
+ * error, so an HTML answer is reported as the missing scope it really is.
+ */
+export async function downloadFile(file, dir) {
+  const url = file.url_private_download || file.url_private;
+  if (!url) throw new Error("Slack gave no download link");
+  if (file.size && file.size > MAX_FILE_BYTES) throw new Error(`too big (${Math.round(file.size / 1048576)}MB)`);
+  const res = await fetch(url, { headers: { Authorization: `Bearer ${botToken()}` }, signal: AbortSignal.timeout(60_000) });
+  if (!res.ok) throw new Error(`Slack: http_${res.status}`);
+  if ((res.headers.get("content-type") ?? "").includes("text/html")) {
+    throw new Error("Slack would not hand it over: the app needs the files:read scope (run slack-setup create again)");
+  }
+  const bytes = Buffer.from(await res.arrayBuffer());
+  if (bytes.length > MAX_FILE_BYTES) throw new Error("too big");
+  fs.mkdirSync(dir, { recursive: true });
+  const target = path.join(dir, safeFileName(file));
+  fs.writeFileSync(target, bytes);
+  return target;
+}
+
+/** Post to a known channel ID (not the configured target), e.g. a reminder beside its question. */
+export async function postToChannel(channel, { text, blocks, thread_ts, color }) {
+  const r = await slackCall("chat.postMessage", botToken(), { channel, ...messageBody({ text, blocks, color }), thread_ts, unfurl_links: false, unfurl_media: false });
+  if (!r.ok) throw new Error(`Slack: ${r.error}`);
+  return { channel: r.channel, ts: r.ts };
+}
+
+/** Link to a message, or null if Slack won't say. */
+export async function permalink(channel, ts) {
+  const url = `${apiBase()}/chat.getPermalink?channel=${encodeURIComponent(channel)}&message_ts=${encodeURIComponent(ts)}`;
+  const res = await fetch(url, { headers: { Authorization: `Bearer ${botToken()}` }, signal: AbortSignal.timeout(15_000) });
+  const r = await res.json().catch(() => ({}));
+  return r.ok ? r.permalink : null;
+}
+
+/** Open a modal in response to a click; `triggerId` is only valid for about 3 seconds. */
+export async function openModal(triggerId, view) {
+  const r = await slackCall("views.open", botToken(), { trigger_id: triggerId, view });
+  if (!r.ok) throw new Error(`Slack: ${r.error}`);
+}
+
+async function slackForm(method, token, params) {
+  const res = await fetch(`${apiBase()}/${method}`, {
+    method: "POST",
+    headers: { Authorization: `Bearer ${token}` },
+    body: new URLSearchParams(params),
+    signal: AbortSignal.timeout(30_000),
+  });
+  return res.json().catch(() => ({ ok: false, error: `http_${res.status}` }));
+}
+
+/**
+ * Upload local files into a channel as one message (Slack's external upload flow:
+ * get an upload URL per file, send the bytes, then complete into the channel).
+ */
+export async function uploadFiles(channel, files, { comment } = {}) {
+  const token = botToken();
+  const uploaded = [];
+  for (const file of files) {
+    const bytes = await fs.promises.readFile(file);
+    const title = path.basename(file);
+    // Diffs uploaded as a "diff" snippet get Slack's syntax highlighting instead of plain text.
+    const snippet = /\.(diff|patch)$/i.test(title) ? { snippet_type: "diff" } : {};
+    const slot = await slackForm("files.getUploadURLExternal", token, { filename: title, length: String(bytes.length), ...snippet });
+    if (!slot.ok) throw new Error(`Slack upload (${title}): ${slot.error}`);
+    const put = await fetch(slot.upload_url, { method: "POST", body: bytes, signal: AbortSignal.timeout(120_000) });
+    if (!put.ok) throw new Error(`Slack upload (${title}): HTTP ${put.status}`);
+    uploaded.push({ id: slot.file_id, title });
+  }
+  const done = await slackForm("files.completeUploadExternal", token, {
+    files: JSON.stringify(uploaded),
+    channel_id: channel,
+    ...(comment ? { initial_comment: comment } : {}),
+  });
+  if (!done.ok) throw new Error(`Slack upload: ${done.error}`);
+  return uploaded.map((f) => f.title);
+}
+
+/** Add an emoji reaction to a message; an existing identical reaction is not an error. */
+export async function removeReaction(channel, ts, name) {
+  const r = await slackCall("reactions.remove", botToken(), { channel, timestamp: ts, name });
+  // `no_reaction` just means it was never there, which is not worth reporting.
+  if (!r.ok && r.error !== "no_reaction") throw new Error(`Slack: ${r.error}`);
+}
+
+export async function addReaction(channel, ts, name) {
+  const r = await slackCall("reactions.add", botToken(), { channel, timestamp: ts, name });
+  if (!r.ok && r.error !== "already_reacted") throw new Error(`Slack: ${r.error}`);
+}
+
+/** The DM channel between the bot and a user. */
+export async function openDm(userId) {
+  const r = await slackCall("conversations.open", botToken(), { users: userId });
+  if (!r.ok) throw new Error(`Slack: ${r.error}`);
+  return r.channel.id;
+}
+
+/** Messages in a channel newer than `oldest` (a Slack ts), oldest first. */
+export async function history(channel, oldest) {
+  const params = new URLSearchParams({ channel, limit: "100", ...(oldest ? { oldest } : {}) });
+  const res = await fetch(`${apiBase()}/conversations.history?${params}`, {
+    headers: { Authorization: `Bearer ${botToken()}` },
+    signal: AbortSignal.timeout(15_000),
+  });
+  const r = await res.json().catch(() => ({ ok: false, error: `http_${res.status}` }));
+  if (!r.ok) throw Object.assign(new Error(`Slack: ${r.error}`), { code: r.error });
+  return (r.messages ?? []).reverse();
+}
+
+/** Replies in a thread newer than `oldest`, oldest first, without the parent. */
+export async function replies(channel, threadTs, oldest) {
+  const params = new URLSearchParams({ channel, ts: threadTs, limit: "100", ...(oldest ? { oldest } : {}) });
+  const res = await fetch(`${apiBase()}/conversations.replies?${params}`, {
+    headers: { Authorization: `Bearer ${botToken()}` },
+    signal: AbortSignal.timeout(15_000),
+  });
+  const r = await res.json().catch(() => ({ ok: false, error: `http_${res.status}` }));
+  if (!r.ok) throw Object.assign(new Error(`Slack: ${r.error}`), { code: r.error });
+  return (r.messages ?? []).filter((m) => m.ts !== threadTs);
+}
+
+/**
+ * Connect to Socket Mode and hand interactive payloads (clicks, modal submits) to `onInteractive`
+ * and Events API events (e.g. DMs to the bot) to `onEvent`. Envelopes are acknowledged immediately.
+ * `onClose` fires once when the socket ends for any reason; reconnecting is the caller's decision.
+ */
+export async function connectSocket({ onInteractive, onEvent, onClose, log = () => {} }) {
+  const token = slackAppToken();
+  if (!token) throw new Error("no app-level Slack token (xapp-…) in ROGER_ROGER_SLACK_APP_TOKEN or SLACK_APP_TOKEN");
+  if (typeof WebSocket !== "function") throw new Error("Socket Mode needs Node 22+ (global WebSocket)");
+
+  const open = await slackCall("apps.connections.open", token, {});
+  if (!open.ok) throw new Error(`Slack Socket Mode: ${open.error}`);
+
+  const ws = new WebSocket(open.url);
+  let closed = false;
+  const finish = (why) => {
+    if (closed) return;
+    closed = true;
+    log(`socket closed: ${why}`);
+    onClose?.(why);
+  };
+
+  ws.addEventListener("message", (event) => {
+    let msg;
+    try {
+      msg = JSON.parse(String(event.data));
+    } catch {
+      return;
+    }
+    if (msg.envelope_id) ws.send(JSON.stringify({ envelope_id: msg.envelope_id }));
+    if (msg.type === "hello") log("socket connected");
+    if (msg.type === "disconnect") {
+      log(`socket asked to reconnect (${msg.reason})`);
+      ws.close();
+    }
+    if (msg.type === "interactive" && msg.payload) {
+      Promise.resolve(onInteractive(msg.payload)).catch((e) => log(`interaction failed: ${e.message}`));
+    }
+    if (msg.type === "events_api" && msg.payload?.event && onEvent) {
+      Promise.resolve(onEvent(msg.payload.event)).catch((e) => log(`event failed: ${e.message}`));
+    }
+  });
+  ws.addEventListener("close", () => finish("close"));
+  ws.addEventListener("error", () => finish("error"));
+
+  return { close: () => ws.close() };
+}

package/skills/roger-roger/scripts/slackapp.mjs

@@ -0,0 +1,205 @@
+// Creating the skill's own Slack app with the Slack CLI, and keeping the tokens it hands over.
+//
+// The Slack CLI only passes an app's tokens to project "hooks", so ~/.roger-roger/slack-app is a
+// minimal Slack CLI project: a copy of the bundled manifest, and a `deploy` hook that calls back
+// into this skill to store the tokens in ~/.roger-roger/slack.json and exit. `slack deploy` creates
+// the app from the manifest on first run, installs it to the workspace, then runs that hook;
+// running it again updates the same app.
+
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { SKILL_DIR, rogerRogerHome, readSlackCredentials, slackCredentialsPath } from "./lib.mjs";
+import { capture, findCli } from "./slackcli.mjs";
+import { apiBase } from "./slack.mjs";
+
+export const MANIFEST_PATH = path.join(SKILL_DIR, "slack", "manifest.json");
+const SCRIPT = path.join(path.dirname(fileURLToPath(import.meta.url)), "roger-roger.mjs");
+
+export function projectDir() {
+  return path.join(rogerRogerHome(), "slack-app");
+}
+
+function saveCredentials(credentials) {
+  const file = slackCredentialsPath();
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, JSON.stringify(credentials, null, 2) + "\n", { encoding: "utf8", mode: 0o600 });
+  try {
+    fs.chmodSync(file, 0o600); // A no-op on Windows, where the user profile is already private.
+  } catch {}
+}
+
+/**
+ * A command line the Slack CLI can run as a hook. It starts with a bare `node`: the CLI runs hooks
+ * through PowerShell on Windows, which rejects a quoted executable path without `&`, while a bare
+ * command followed by a quoted script path works there and in sh alike.
+ */
+export function hookCommand(name, script = SCRIPT) {
+  const quote = (p) => (/[\s'"]/.test(p) ? `"${p}"` : p);
+  return `node ${quote(script)} slack-hook ${name}`;
+}
+
+export function hooksConfig() {
+  return { hooks: { "get-hooks": hookCommand("get-hooks"), deploy: hookCommand("deploy") } };
+}
+
+/** Write (or refresh) the project. The app IDs the CLI keeps in .slack/apps.json are left alone. */
+function writeProject() {
+  const dir = projectDir();
+  fs.mkdirSync(path.join(dir, ".slack"), { recursive: true });
+  fs.writeFileSync(path.join(dir, ".slack", "hooks.json"), JSON.stringify(hooksConfig(), null, 2) + "\n");
+  // The CLI reads manifest.json from the project root; the skill ships the source of truth.
+  fs.copyFileSync(MANIFEST_PATH, path.join(dir, "manifest.json"));
+  const configFile = path.join(dir, ".slack", "config.json");
+  if (!fs.existsSync(configFile)) fs.writeFileSync(configFile, JSON.stringify({ manifest: { source: "local" } }, null, 2) + "\n");
+  return dir;
+}
+
+/** The app the CLI created for this project, if any. */
+export function linkedApp() {
+  try {
+    const apps = JSON.parse(fs.readFileSync(path.join(projectDir(), ".slack", "apps.json"), "utf8"));
+    const app = Object.values(apps.apps ?? {})[0];
+    return app ? { appId: app.app_id, teamId: app.team_id } : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Handle a hook invocation from the Slack CLI. Returns the process exit code. */
+export function runHook(name, env = process.env) {
+  if (name === "get-hooks") {
+    process.stdout.write(JSON.stringify(hooksConfig()));
+    return 0;
+  }
+  if (name !== "deploy") {
+    process.stderr.write(`roger-roger: unknown hook "${name}"\n`);
+    return 1;
+  }
+  const botToken = env.SLACK_CLI_XOXB || env.SLACK_BOT_TOKEN || "";
+  const appToken = env.SLACK_CLI_XAPP || env.SLACK_APP_TOKEN || "";
+  if (!botToken.startsWith("xoxb-")) {
+    process.stderr.write("roger-roger: the Slack CLI did not provide a bot token\n");
+    return 1;
+  }
+  saveCredentials({
+    source: "slack-cli",
+    botToken,
+    appToken: appToken.startsWith("xapp-") ? appToken : "",
+    savedAt: new Date().toISOString(),
+  });
+  process.stdout.write(`roger-roger: saved Slack credentials to ${slackCredentialsPath()}\n`);
+  return 0;
+}
+
+// ---------------------------------------------------------------- driving the Slack CLI
+
+/** `slack auth list` text → [{ team, teamId, userId }]. */
+export function parseAuthList(text) {
+  const accounts = [];
+  const re = /^(.+?) \(Team ID: (\w+)\)\s*\r?\nUser ID: (\w+)/gm;
+  for (let m; (m = re.exec(text)); ) accounts.push({ team: m[1].trim(), teamId: m[2], userId: m[3] });
+  return accounts;
+}
+
+/** The `/slackauthticket …` line from `slack login --no-prompt`. */
+export function parseTicket(text) {
+  const m = /\/slackauthticket\s+(\S+)/.exec(text);
+  return m ? { command: `/slackauthticket ${m[1]}`, ticket: m[1] } : null;
+}
+
+function cleanOutput(text) {
+  return text.replace(/<[a-z-]+-hint[^>]*\/>/g, "").trim();
+}
+
+/**
+ * Run the Slack CLI. Token variables are removed from its environment: the CLI prefers
+ * SLACK_BOT_TOKEN / SLACK_APP_TOKEN from the environment over the app's own tokens, which would
+ * hand the deploy hook some other app's credentials.
+ */
+async function slack(cli, args, opts = {}) {
+  const env = { ...process.env };
+  for (const k of ["SLACK_BOT_TOKEN", "SLACK_APP_TOKEN", "SLACK_CLI_XOXB", "SLACK_CLI_XAPP"]) delete env[k];
+  const r = await capture(cli.command, [...args, "--skip-update"], { env, timeout: 180_000, ...opts });
+  return { ...r, out: cleanOutput(`${r.stdout}\n${r.stderr}`) };
+}
+
+async function requireCli() {
+  const cli = await findCli();
+  if (!cli) throw new Error("the Slack CLI is not installed: run `slack-setup install-cli`");
+  return cli;
+}
+
+export async function accounts(cli) {
+  const r = await slack(cli, ["auth", "list"]);
+  return r.code === 0 ? parseAuthList(r.out) : [];
+}
+
+async function tokenWorks(method, token) {
+  if (!token) return false;
+  try {
+    const res = await fetch(`${apiBase()}/${method}`, { method: "POST", headers: { Authorization: `Bearer ${token}` }, signal: AbortSignal.timeout(15_000) });
+    return Boolean((await res.json()).ok);
+  } catch {
+    return false;
+  }
+}
+
+/** Where onboarding stands, and the next step to take. */
+export async function setupStatus({ checkTokens = true } = {}) {
+  const cli = await findCli();
+  const logins = cli ? await accounts(cli) : [];
+  const stored = readSlackCredentials();
+  const credentials = stored
+    ? {
+        path: slackCredentialsPath(),
+        botToken: checkTokens ? await tokenWorks("auth.test", stored.botToken) : Boolean(stored.botToken),
+        appToken: checkTokens ? await tokenWorks("apps.connections.open", stored.appToken) : Boolean(stored.appToken),
+      }
+    : null;
+  const next = !cli ? "install-cli" : !logins.length ? "login" : !(credentials?.botToken && credentials?.appToken) ? "create" : "done";
+  return { cli, logins, app: linkedApp(), credentials, next };
+}
+
+/** Step 1 of login: a ticket the user runs as a slash command in Slack. */
+export async function loginStart() {
+  const cli = await requireCli();
+  const r = await slack(cli, ["login", "--no-prompt"]);
+  const ticket = parseTicket(r.out);
+  if (r.code !== 0 || !ticket) throw new Error(`slack login failed: ${r.out}`);
+  return ticket;
+}
+
+/** Step 2 of login: the challenge code Slack showed the user. */
+export async function loginFinish({ challenge, ticket }) {
+  const cli = await requireCli();
+  const r = await slack(cli, ["login", "--challenge", challenge, "--ticket", ticket]);
+  if (r.code !== 0) throw new Error(`slack login failed: ${r.out}`);
+  return accounts(cli);
+}
+
+/**
+ * Create (or update) the roger-roger app from the manifest in a workspace, install it, and save its
+ * tokens. `teamId` may be omitted when the CLI is logged in to exactly one workspace.
+ */
+export async function createApp({ teamId } = {}) {
+  const cli = await requireCli();
+  const logins = await accounts(cli);
+  if (!logins.length) throw new Error("the Slack CLI is not logged in: run `slack-setup login`");
+  const account = teamId ? logins.find((a) => a.teamId === teamId || a.team === teamId) : logins.length === 1 ? logins[0] : null;
+  if (!account) {
+    throw new Error(`choose a workspace with --team: ${logins.map((a) => `${a.team} (${a.teamId})`).join(", ")}`);
+  }
+
+  const cwd = writeProject();
+  const r = await slack(cli, ["deploy", "--team", account.teamId], { cwd });
+  if (r.code !== 0) throw new Error(`slack deploy failed: ${r.out}`);
+
+  const stored = readSlackCredentials();
+  const botOk = await tokenWorks("auth.test", stored?.botToken);
+  const appOk = await tokenWorks("apps.connections.open", stored?.appToken);
+  if (!botOk || !appOk) {
+    throw new Error(`the app was installed but its ${botOk ? "app-level" : "bot"} token does not work; run \`slack-setup create\` again`);
+  }
+  return { ...linkedApp(), team: account.team, userId: account.userId };
+}