Repository navigation
feat(settings): a step-by-step Slack setup wizard - #39005
iamwhatever wants to merge 2 commits into
Conversation
First Principles Review (Opus 5.5) — 🔴 BLOCKPremise-level review of First-Principles-Verdict: BLOCK The new Notes
What this change shipsInventory (10 items) — 8 justifiedIntent: help a first-time user set up Slack one screen at a time, with no gateway restart. ADDITION.
BlockersThe [FIRST-PRINCIPLES-REVIEWED] 90483b9 Description read[DESCRIPTION-READ] 4cf990c277d0863c5fe302c3fcf77356aab7da5dcdfb63c2ac846422d051a6a4 That sha256 names the PR description this verdict read. Recompute it with |
Design Review (Opus 5.5) — ✅ PASSDesign-level review of Design-Verdict: PASS Nothing blocks: the wizard reuses the existing local-only config and reconnect routes, the backend adds only link helpers, and screenshots of every step are attached. Notes
[DESIGN-REVIEWED] 90483b9 Description read[DESCRIPTION-READ] 70e81f1ab4c189a1109e310b94abdba608371573a4f4f409902398e18939612d That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with |
UX Review (Opus 5.5) — ✅ PASS (a BLOCK with no Trigger and no Outcome does not block)UX-level review of UX-Verdict: PASS cannot evaluate: missing the panel-level "Setup wizard" reopen button, the wizard's place in the Slack panel, and the step error states. Every screenshot is cropped to the wizard card. Evidence gaps
Notes
[UX-REVIEWED] 90483b9 Description read[DESCRIPTION-READ] 489bf90323b53157b6987be1ff658122a7113a508e4d10404249009276554031 That sha256 names everything this verdict read: the PR description, plus the 17 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with |
Opus 5.5 Review — ✅ no blocking findingsReviewed Verdict parsed from the review's SHA-scoped output markers for commit False positive or not applicable? A repository writer can comment: |
GPT 6.1 Review — 🔴 changes requested (blocking)GPT 6.1 found at least one blocking issue that must be resolved before merging This comment is updated in place on each push. BLOCKING -- website/src/pages/settings/SlackPanel.tsx:506 -- Wizard saves discard unrelated unsaved form edits
[BLOCK-MERGE] 90483b9 Adjudication (Opus 5.5) — is blocking on each finding proportionate?The wizard is open by default until Slack connects ( False positive or not applicable? A repository writer can comment: |
26b250a to
90483b9
Compare
Basic Information page, bot DM link, and a create link that keeps the saved slash command. Refs #38917
90483b9 to
6380ec5
Compare
Problem / Motivation
Goal: Settings → Messaging channels → Slack walks a first-time user from "I have a workspace" to "the bot answered my message" one screen at a time, with a picture of where to click on Slack's pages, and no gateway restart.
Today's panel is a long form: one Create link, two token fields and a member-ID field, with the steps in between left to a guide. A recorded first-time setup took 12 manual steps, 3 pastes and 2 gateway restarts, renamed the app by hand (every one-click app is
KiroCrew-kirocrew) and toggled Socket Mode off and on to find the app-level token page.This is the UI half (C2) of #38917. It stacks on #38918 (C1, the link helpers); until that merges this PR also shows C1's commit.
Why it matters
Slack setup is where people give up. The restarts were never needed (Reconnect applies saved credentials and a first owner), and the rename and token-page hunt go away once the app is named after an alias and the page is linked.
Not a goal
What changed (motivation → approach → change)
New
website/src/pages/settings/SlackSetupWizard.tsx, shown at the top of the Slack panel until Slack first connects (and kept open for the last step), reopenable from a "Setup wizard" button:GET /api/slack/manifest?alias=for the link; on click savesslack.commandto the command that manifest registers, so "Update the Slack app" later keeps the alias name instead of reverting toKiroCrew-kirocrewxoxb-auth.test); notes that company workspaces may need admin approval ("Request to Install")xapp-app_redirectlink from C1), sends a messageEvery step has a schematic (
SlackWizardDiagram.tsx, positioned elements, no inline SVG per the use-lucide-icons rule): a simplified frame of the Slack page or client with the target outlined (dashed, so it never reads as a button here) and numbered in click order, under a caption saying it is a picture and not clickable. Colors are theme variables only, so every theme including dark reads; no Slack screenshots are shipped. Words in the pictures go through the catalog; Slack's own button and page names keep Slack's English spelling in every locale (api.slack.com is English-only), with a short role word ("button", "page") beside them in non-Latin locales.Other changes:
SlackPanel.tsx: mounts the wizard; a wizard save re-arms the form's draft sync so a later form save cannot send a stale owner back; the Setup guide link now points todocs/guides/slack-setup.mdinstead of the oldest doc.messaging.ts:getSlackManifest(alias?), and the two new status URLs.docs/feature-map/README.md: a row for the wizard.slack-manifest.yamlheader comment: drop the "toggle Socket Mode off and on" trick, name the direct path and the wizard. Comment only, no scope or field change.en-XA.website/scripts/capture-slack-setup-wizard.mjs: the screenshot harness below.Still to come in this PR, after #38938 (slash-command hot reload) merges, because it edits the same files: the optional organization guide link setting (
slack.setup_guide_url:https://only, set on this machine only, rendered withrel="noopener noreferrer"), and the guide update indocs/guides/slack-setup.md. The frontend half of the guide link (safeGuideUrl, rendering, tests) is already here and shows nothing until the setting exists.Backwards compatibility
Compatible: the wizard uses the existing local-only
PUT /api/slack/configandPOST /api/slack/reconnect; the form below it is unchanged.Removes nothing: the panel keeps every field; only the Setup guide link target and a manifest comment change.
Tests
website/src/test/SlackSetupWizard.test.tsx(21 tests): the start step follows the saved config; the org guide renders only forhttps://(nothttp:,javascript:, credentials in the URL) and withrel="noopener noreferrer"; an alias the backend would refuse disables Create and fetches nothing; Create saves the alias's slash command; the bot-token save sends only the token and moves on; a rejected token stays on its step with Slack's error; the app-level token step does not reconnect; the owner step saves and reconnects without a restart; a refused reconnect is described with the panel's own wording; the last step finishes only on "I got a reply"; a read-only remote viewer gets no inputs; every step draws its picture.tsc,eslint,npm run i18n:checkwith baseorigin/main(all 19 checks pass), vitest on the Slack panel suites andsrc/i18n(1345 passed), backend Slack manifest/exfil tests, brand gate.Proof: not provable -- frontend test (prove.py runs Python only)
Manual verification
Screenshots below come from the real built SPA with canned Slack responses (
node website/scripts/capture-slack-setup-wizard.mjs); the harness walks every step and asserts the step, its link and that Create savedslack.commandbefore each shot. The harness surfaced one bug, fixed here: the wizard hid itself as soon as Slack connected, before the test step.Not tested live (no Slack app was created, no token used):
https://api.slack.com/apps/<A>/generallands on Basic Information with App-Level Tokens (F10);https://slack.com/app_redirect?app=<A>&team=<T>opens the bot DM on an Enterprise Grid workspace.Screenshots / video
Dark theme, every step:
Light theme and the finished state
Related Issues
Part of #38917. Stacks on #38918.
Checklist
docs/guides/slack-setup.mdfollows after feat(slack): answer /kirocrew-<alias> and apply slack.command without a restart #38938Contribution License Agreement
Contributed under the project's Apache-2.0 license.