wtclaude
61abb3ec89
TEAMS.md §7.3. Each qualifying Team gets a Discord voice channel of its own
and a role that opens it, kept in step by a reconciler that rides the Team
reconcile it already depends on.
Access is a per-Team ROLE, always. §7.3 designed per-member overwrites with
escalation to a role above ~90 members; the org lead settled on roles always
(2026-08-18), which deletes `voice_overwrite_max`, the escalation and the
`mode` column — and moves the ceiling. Overwrites are capped per channel, so
the old shape's limit was "how big can one Team be"; roles are capped per
guild at 250, so the new one is "how many Teams can have voice at all". That
is a limit an operator must be told about before they hit it, so the panel
reports it and the pass refuses the create rather than letting Discord do it.
Three things §7.3 named that this codebase does not have, all settled by
asking the operator because nothing in the data model can answer:
- "the staff role" — there is no staff-role concept anywhere. Now a list of
role ids the admin designates; empty is a normal answer, since guild
administrators bypass overwrites and what is really missing is a way to
let NON-admin staff in.
- the parent category — §7.3 said the bot creates it and gave the id nowhere
to live (`team_integrations.team_id` is NOT NULL). The bot creates it and
the server stores the id in settings.
- whether the bot can act at all — nothing has ever checked. The operator
invites the bot by hand and no invite URL with a permission integer exists
in the tree, so a deployment can be one unticked box from every call
failing. A preflight is now a PRECONDITION to enabling (422), not a
per-Team error discovered afterwards.
Two more, decided rather than asked:
- the threshold counts every active member, not linked ones. §7.3 wrote
`voice_min_linked_members`; the operator is judging whether a Team is real,
and link state answers a different question.
- hidden Teams are never provisioned. A channel name is a game-sourced string
published outside the site, which is exactly §2.8's concern —
reservedNames.js already names "and eventually a Discord channel name" as a
surface it protects — so the screen that suppresses a Team's page suppresses
its channel, and a Team that becomes hidden takes the grace window.
Turning voice OFF tears nothing down: the pass suspends in both directions and
the panel offers per-row removal. A checkbox must not delete structure in
somebody's guild.
Fixes a phase 8 defect that blocks this phase's own artifact: `npm run swagger`
has been unable to run on `edge` at all. `param('teamId').custom((v) => ... ||
/^[0-9]+$/.test(v))` makes swagger-autogen's parser run away — a regex literal
followed directly by `.test(`. Hoisted to a const, as modules.router.js
already does. Underneath it, `teams.router.js` sits exactly at that parser's
per-file limit: at twenty `teamsRouter.*` statements it dies, at nineteen it
generates, and one more statement of ANY shape tips it — an unannotated route
does, and so does a bare `use`. So the voice routes are their own router file
mounted from `admin/index.js`, and teams.router.js keeps its nineteen.
Also breaks a require cycle this phase would have introduced:
teamSync -> teamVoiceSync -> teams.model -> teamSync left `teams.model` holding
the reconciler's exports object as it stood mid-load — the empty one, since
`module.exports = {…}` replaces rather than fills. The symptom is not in the
new code: it is `teamSync.intervalSeconds is not a function` thrown out of
`syncStatus()`, the freshness banner on every public Team page.
Tests: 1160 server (+40), 53 bot (+21), 284 client (+21). Swagger, routes
manifest and guards regenerated; the guard shape of the four new routes is
byte-identical to the existing admin-only ones.
Co-Authored-By: Claude <noreply@anthropic.com>
113 lines
5.0 KiB
JavaScript
113 lines
5.0 KiB
JavaScript
// What Admin → Teams → Voice channels decides (TEAMS.md §7.3, phase 9).
|
||
//
|
||
// Extracted for the reason `teamIntegrations.js` is: the interesting parts are
|
||
// decisions — when the panel refuses to let voice be switched on, how close the
|
||
// guild is to running out of roles, what a row's state actually means to the
|
||
// person reading it — and a decision written inline in JSX is one nothing can
|
||
// assert on.
|
||
//
|
||
// **These rules MIRROR the server's and do not replace them.** The server refuses
|
||
// to enable voice while the bot cannot manage channels and roles (422) whether or
|
||
// not this file ever ran, and the reconciler applies the threshold and the grace
|
||
// window regardless of what the screen says. What is here is so the screen agrees
|
||
// with those answers before making the round trip.
|
||
|
||
/** Wording for each state the server can report on a row. */
|
||
export const STATE_LABELS = {
|
||
none: 'Not provisioned',
|
||
active: 'Active',
|
||
pending_removal: 'Scheduled for removal',
|
||
error: 'Error',
|
||
}
|
||
|
||
export const stateLabel = (state) => STATE_LABELS[state] || state || 'Unknown'
|
||
|
||
/**
|
||
* Is the panel allowed to offer the enable switch?
|
||
*
|
||
* The preflight answers three separate questions and they fail differently: the
|
||
* bot is not connected at all, it is connected but missing a permission, or it
|
||
* could not be reached. An operator can act on each of those and they need
|
||
* different actions, so the reason is passed through rather than flattened to a
|
||
* boolean.
|
||
*/
|
||
export function enableBlockedReason(preflight) {
|
||
if (!preflight) return 'The bot’s status is unknown.'
|
||
if (!preflight.connected) return preflight.reason || 'The Discord bot is not connected.'
|
||
if (preflight.missingPermissions && preflight.missingPermissions.length > 0) {
|
||
return `The bot is missing ${preflight.missingPermissions.join(' and ')} in this guild.`
|
||
}
|
||
if (!preflight.ready) return preflight.reason || 'The bot cannot manage channels and roles yet.'
|
||
return null
|
||
}
|
||
|
||
// Below this many free roles the panel starts saying so. Not a server rule and
|
||
// deliberately not one: it is a warning, and the server's only hard behaviour is
|
||
// to refuse the create that would exceed the cap.
|
||
const HEADROOM_WARNING = 25
|
||
|
||
/**
|
||
* How much room is left, and whether to say something about it.
|
||
*
|
||
* The 250-role cap is the ceiling this phase's shape brings with it. Access is a
|
||
* per-Team role, so it is not "how big can a Team be" — the old overwrite design's
|
||
* limit — but "how many Teams can have voice at all", and the difference matters
|
||
* to an operator with sixty guilds on their shard. It is guild-wide and shared
|
||
* with every role they created themselves, which is why the count comes from the
|
||
* bot rather than from core's own rows.
|
||
*/
|
||
export function roleHeadroom(preflight) {
|
||
if (!preflight || !preflight.roleCap) return null
|
||
const used = Number(preflight.roleCount) || 0
|
||
const cap = Number(preflight.roleCap)
|
||
const free = Math.max(0, cap - used)
|
||
return { used, cap, free, tight: free <= HEADROOM_WARNING, exhausted: free === 0 }
|
||
}
|
||
|
||
/** How a row's grace window reads while it is running. */
|
||
export function removalCountdown(row, now = new Date()) {
|
||
if (!row || row.state !== 'pending_removal' || !row.removeAfter) return null
|
||
const ms = new Date(row.removeAfter).getTime() - now.getTime()
|
||
if (ms <= 0) return 'due for removal on the next pass'
|
||
const days = Math.floor(ms / 86400000)
|
||
if (days >= 1) return `in ${days} day${days === 1 ? '' : 's'}`
|
||
const hours = Math.max(1, Math.round(ms / 3600000))
|
||
return `in ${hours} hour${hours === 1 ? '' : 's'}`
|
||
}
|
||
|
||
/**
|
||
* Parse the staff-role field an operator types.
|
||
*
|
||
* Comma-separated ids, because that is what a person copying role ids out of
|
||
* Discord ends up with. Validated rather than filtered, mirroring the server: a
|
||
* quietly dropped id is a settings screen showing a save that did not happen.
|
||
*/
|
||
export function parseStaffRoles(text) {
|
||
const parts = String(text || '')
|
||
.split(',')
|
||
.map((part) => part.trim())
|
||
.filter(Boolean)
|
||
const bad = parts.filter((part) => !/^[0-9]{5,32}$/.test(part))
|
||
return { roles: parts, invalid: bad }
|
||
}
|
||
|
||
export const formatStaffRoles = (roles) => (roles || []).join(', ')
|
||
|
||
/**
|
||
* The sentence under the enable switch, which changes meaning with the state.
|
||
*
|
||
* "Off" is not "nothing is provisioned": switching voice off suspends the
|
||
* reconciler in BOTH directions and leaves existing channels in place, which is
|
||
* deliberate — a checkbox must not delete structure in somebody's guild — but it
|
||
* is also surprising unless the screen says so.
|
||
*/
|
||
export function statusSummary(settings, rows) {
|
||
const provisioned = (rows || []).filter((row) => row.channelRef).length
|
||
if (!settings || !settings.enabled) {
|
||
return provisioned > 0
|
||
? `Off. ${provisioned} channel${provisioned === 1 ? '' : 's'} remain in Discord and are no longer being kept in step — remove them below if they are not wanted.`
|
||
: 'Off. No channels are provisioned.'
|
||
}
|
||
return `On. Teams with at least ${settings.minMembers} member${settings.minMembers === 1 ? '' : 's'} get a voice channel and a role; ${provisioned} provisioned.`
|
||
}
|