limn-review 0.1.123

package/dist/api/routes/contact.js

@@ -0,0 +1,318 @@
+// The public contact form: POST /api/contact, delivered to a Slack incoming webhook.
+//
+// WHY SLACK AND NOT EMAIL. A contact form's job is to make sure a message ARRIVES.
+// Email is the medium with the worst odds of that: it bounces, it lands in spam, and
+// it needs SPF/DKIM/DMARC on the domain plus a transactional provider before the first
+// message even has a chance. A webhook POST either returns 2xx or throws, and the
+// failure is visible in this process's logs at the moment it happens. There is also
+// precedent and a working shape already in the repo — the Pro plugin's per-workspace
+// digest delivery (packages/pro/src/slack/) — though core cannot import from the
+// plugin, so the URL validation below is a deliberate small copy rather than a shared
+// helper. Email can be added later as a SECOND sink; it should never be the only one.
+//
+// ⚠ NO NEW DEPENDENCY, AND THAT IS A CONSTRAINT RATHER THAN A PREFERENCE.
+// scripts/build-release.mjs generates release/package.json from a CURATED dependency
+// list, so an SDK here ships to every `npx pierre-review` install for the sake of a
+// hosted-only marketing page. Node ≥20's global fetch is the whole client.
+//
+// ---- Deciding a submission is genuine ----
+//
+// Three layers, none of which needs a third party, a script tag or a CSP change (the
+// landing's CSP is `default-src 'self'` with `frame-src` absent entirely — a Turnstile
+// or reCAPTCHA widget would need `script-src` AND `frame-src` widened, plus a line in
+// the privacy policy, which is a decision worth taking deliberately rather than as a
+// side effect of shipping a form):
+//
+//   1. A HONEYPOT field. `website` is rendered, labelled and reachable in the DOM, and
+//      hidden from sighted users by CSS + aria-hidden + tabindex=-1. A person never
+//      fills it; a form-filling bot fills every input it finds. A filled honeypot is
+//      answered with 200 and DROPPED — never a 400, because an error tells whoever is
+//      running the bot exactly which field gave them away.
+//
+//   2. A SIGNED TICKET with a minimum fill time. GET /api/contact/ticket returns
+//      `<issuedAtMs>.<hmac>`; the POST verifies the signature and requires the age to
+//      sit between MIN_FILL_MS and MAX_TICKET_MS. This is the layer that a client-sent
+//      "elapsed" number cannot be: the timestamp is signed by this server, so a bot
+//      cannot forge an age, and to get a valid one it has to make a second request and
+//      then WAIT. Stateless on purpose — no store, no replay table. A ticket is
+//      therefore reusable within its window, which the rate limit below bounds.
+//
+//   3. A RATE LIMIT. The `contact` tier in api/plugins/rate-limit.ts, keyed by IP
+//      because this route is deliberately anonymous. Five an hour.
+//
+// A determined human will still get a message through, which is correct — the target
+// is automated submission volume, not a wall.
+import { createHmac, randomBytes, timingSafeEqual } from 'node:crypto';
+import { config } from '../../config.js';
+// ---------------------------------------------------------------------------
+// The ticket
+// ---------------------------------------------------------------------------
+/** A person needs longer than this to write a message. Below it, it was not typed. */
+export const MIN_FILL_MS = 3_000;
+/** Past this the ticket is stale — a page left open, or one harvested days ago. */
+export const MAX_TICKET_MS = 6 * 60 * 60 * 1000;
+// The signing key. SESSION_SECRET where there is one (cloud, where this form actually
+// runs), otherwise a per-process random — which means a restart invalidates every
+// outstanding ticket. That is acceptable and better than a constant: the failure mode
+// is one visitor being asked to reload, and the alternative is a key an attacker can
+// read out of the source.
+//
+// Derived rather than used directly so this never shares key material with the session
+// cookie: the same secret signing two different things is how one forgery becomes two.
+const TICKET_KEY = createHmac('sha256', config.sessionSecret || randomBytes(32))
+    .update('pierre:contact-ticket:v1')
+    .digest();
+function sign(issuedAtMs) {
+    return createHmac('sha256', TICKET_KEY).update(String(issuedAtMs)).digest('hex');
+}
+/** Mint a ticket for a form that is being opened now. */
+export function issueTicket(nowMs = Date.now()) {
+    return `${nowMs}.${sign(nowMs)}`;
+}
+/**
+ * Check a ticket's signature and age. Pure — `nowMs` is injected so the windows can be
+ * tested without waiting for them.
+ */
+export function verifyTicket(raw, nowMs = Date.now()) {
+    if (typeof raw !== 'string')
+        return 'malformed';
+    const dot = raw.indexOf('.');
+    if (dot <= 0)
+        return 'malformed';
+    const issuedAt = Number.parseInt(raw.slice(0, dot), 10);
+    const mac = raw.slice(dot + 1);
+    if (!Number.isFinite(issuedAt) || mac === '')
+        return 'malformed';
+    // Constant-time, and length-checked first: timingSafeEqual THROWS on a length
+    // mismatch rather than returning false, so an attacker-supplied short mac would be a
+    // 500 instead of a 400.
+    const expected = Buffer.from(sign(issuedAt), 'utf-8');
+    const got = Buffer.from(mac, 'utf-8');
+    if (got.length !== expected.length || !timingSafeEqual(got, expected)) {
+        return 'bad_signature';
+    }
+    const age = nowMs - issuedAt;
+    // A negative age means a clock moved, not an attack — it is signed, so it can only
+    // have been minted here. Treated as "too fast", which is the safe side.
+    if (age < MIN_FILL_MS)
+        return 'too_fast';
+    if (age > MAX_TICKET_MS)
+        return 'expired';
+    return 'ok';
+}
+// ---------------------------------------------------------------------------
+// The webhook URL
+// ---------------------------------------------------------------------------
+const SLACK_WEBHOOK_HOST = 'hooks.slack.com';
+/**
+ * Validate and normalise a Slack incoming-webhook URL.
+ *
+ * A near-copy of the Pro plugin's `normalizeSlackWebhookUrl` — core cannot import from
+ * `packages/pro` (it is a private submodule loaded by path, absent in OSS builds), so
+ * this is duplicated deliberately rather than shared. Keep the two in step.
+ *
+ * The value arrives from the environment, so the threat is a misconfiguration or a
+ * compromised variable turning this process into an SSRF proxy, not a user submission.
+ * Validating at the SINK makes the guarantee structural.
+ */
+export function normalizeContactWebhookUrl(raw) {
+    const t = raw.trim();
+    if (t === '')
+        return null;
+    let url;
+    try {
+        url = new URL(t);
+    }
+    catch {
+        return null;
+    }
+    // https only: the secret is in the path, so http would leak it on the wire, and the
+    // scheme check also rules out file:/gopher:/ftp: redirect tricks.
+    if (url.protocol !== 'https:')
+        return null;
+    // Exact host. NOT endsWith('slack.com'), which accepts hooks.slack.com.evil.example.
+    if (url.hostname.toLowerCase() !== SLACK_WEBHOOK_HOST)
+        return null;
+    // A real webhook is /services/<team>/<bot>/<token>.
+    if (!url.pathname.startsWith('/services/'))
+        return null;
+    // Query and fragment are dropped — nothing legitimate uses them, and they are a
+    // place to hide a redirect target.
+    return `https://${SLACK_WEBHOOK_HOST}${url.pathname}`;
+}
+/** What the form offers, and what each one means when it lands in Slack. */
+export const CONTACT_TOPICS = {
+    pro_trial: 'Free Pro month',
+    question: 'Question about the product',
+    problem: 'Something is broken',
+    other: 'Something else',
+};
+/**
+ * Slack's own escaping rules: `&`, `<` and `>` are the only three characters that are
+ * special in message text, and they must be escaped BEFORE the markup is assembled.
+ * Applied to every visitor-supplied string so a submission cannot forge a link, a
+ * channel reference or an @-mention in the notification it produces.
+ */
+function slackEscape(s) {
+    return s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}
+/**
+ * Build the Block Kit payload. Pure, so the test asserts the shape and the escaping
+ * without a network.
+ *
+ * The message is ONE block per fact plus the body, because a contact form's whole
+ * value is that the reply address is readable at a glance on a phone.
+ */
+export function buildContactMessage(s) {
+    // `?? 'Something else'` rather than `?? CONTACT_TOPICS['other']`: under
+    // noUncheckedIndexedAccess the second lookup is `string | undefined` too, so it
+    // would not narrow. The literal is the same string the 'other' key holds.
+    const topic = CONTACT_TOPICS[s.topic] ?? 'Something else';
+    // Angle brackets around the address would only be escaped back into literal ones, so
+    // the notification line uses parentheses and reads the same in every client.
+    const summary = `${topic} — ${s.name} (${s.email})`;
+    return {
+        // `text` is the notification line and the fallback for any client that cannot
+        // render blocks. Escaped like everything else.
+        text: slackEscape(summary),
+        blocks: [
+            {
+                type: 'section',
+                text: { type: 'mrkdwn', text: `*${slackEscape(topic)}*` },
+            },
+            {
+                type: 'section',
+                fields: [
+                    { type: 'mrkdwn', text: `*From*\n${slackEscape(s.name)}` },
+                    { type: 'mrkdwn', text: `*Reply to*\n${slackEscape(s.email)}` },
+                ],
+            },
+            {
+                type: 'section',
+                text: { type: 'mrkdwn', text: slackEscape(s.message) },
+            },
+        ],
+    };
+}
+/** POST the message. Throws on a non-2xx so the route can log it and 502. */
+export async function postContactToSlack(webhookUrl, message) {
+    const safe = normalizeContactWebhookUrl(webhookUrl);
+    if (!safe)
+        throw new Error('CONTACT_SLACK_WEBHOOK_URL is not a Slack webhook URL');
+    const res = await fetch(safe, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify(message),
+        // Never follow a redirect: a 30x is the standard way past a host allowlist that
+        // was only applied to the first URL.
+        redirect: 'error',
+        signal: AbortSignal.timeout(10_000),
+    });
+    if (!res.ok) {
+        // The response BODY is deliberately not surfaced — including it would turn a
+        // failed request into a read primitive (point the webhook at something internal
+        // and the error tells you what it said). The status is enough to diagnose.
+        throw new Error(`Slack webhook responded ${res.status}`);
+    }
+}
+// ---------------------------------------------------------------------------
+// The routes
+// ---------------------------------------------------------------------------
+// Length caps are on the SCHEMA, so an oversized body is rejected by Fastify before any
+// of this file runs. Sized for a real message rather than for an essay: Slack truncates
+// a section block past 3000 characters anyway, and a 4000-character contact-form
+// message is not a contact-form message.
+const BODY_SCHEMA = {
+    type: 'object',
+    required: ['name', 'email', 'message', 'ticket'],
+    additionalProperties: false,
+    properties: {
+        name: { type: 'string', minLength: 1, maxLength: 120 },
+        // A deliberately loose pattern. Email addresses that are legal and that a strict
+        // regex rejects are common; the address is only ever used as a reply-to that a
+        // human reads, never as a delivery target, so a wrong one costs a reply and
+        // nothing else.
+        email: { type: 'string', minLength: 3, maxLength: 254, pattern: '^[^@\\s]+@[^@\\s]+\\.[^@\\s]+$' },
+        topic: { type: 'string', enum: Object.keys(CONTACT_TOPICS) },
+        message: { type: 'string', minLength: 1, maxLength: 2500 },
+        ticket: { type: 'string', minLength: 1, maxLength: 200 },
+        // The honeypot, and IT MUST BE DECLARED HERE OR THE WHOLE LAYER IS INERT. Fastify
+        // configures ajv with `removeAdditional: true`, so an undeclared property is
+        // SILENTLY STRIPPED from req.body before the handler runs — the request still 200s,
+        // the check below still sees `undefined`, and every bot passes. Verified by injection,
+        // not assumed: an unknown field posted to this route returns 200 with the field gone.
+        website: { type: 'string', maxLength: 200 },
+    },
+};
+export async function contactRoutes(app) {
+    const configured = normalizeContactWebhookUrl(config.contactSlackWebhookUrl) != null;
+    // Mint a ticket. Also the form's readiness probe: with no webhook configured it 503s
+    // here, so the page can say so BEFORE someone writes two hundred words into a form
+    // that has nowhere to send them.
+    app.get('/api/contact/ticket', async (_req, reply) => {
+        if (!configured) {
+            return reply.code(503).send({ error: 'contact_unavailable' });
+        }
+        // A ticket is a signed timestamp and nothing else — it identifies no one and
+        // carries no state — but it must not be cached by anything in front of this
+        // server, or every visitor shares one issue time.
+        reply.header('cache-control', 'no-store');
+        return { ticket: issueTicket() };
+    });
+    app.post('/api/contact', { schema: { body: BODY_SCHEMA } }, async (req, reply) => {
+        if (!configured) {
+            return reply.code(503).send({
+                error: 'contact_unavailable',
+                message: 'The contact form is not available right now.',
+            });
+        }
+        const body = req.body;
+        // Layer 1. Answered with the SUCCESS shape on purpose: a bot that is told it failed
+        // learns which field to leave alone next time, and a person can never reach this.
+        if (typeof body.website === 'string' && body.website.trim() !== '') {
+            req.log.info({ ip: req.ip }, 'contact form: honeypot filled, dropped');
+            return { ok: true };
+        }
+        // Layer 2.
+        const verdict = verifyTicket(body.ticket);
+        if (verdict !== 'ok') {
+            req.log.warn({ ip: req.ip, verdict }, 'contact form: ticket rejected');
+            // Two answers, because they mean different things to a person. An expired ticket
+            // is a page that sat open and the fix is to reload; anything else is either a bot
+            // or a genuinely broken client, and the message says what to do without saying
+            // which check failed.
+            return reply.code(400).send({
+                error: verdict === 'expired' ? 'ticket_expired' : 'ticket_invalid',
+                message: verdict === 'expired'
+                    ? 'This form has been open for a while. Reload the page and send it again.'
+                    : 'We could not verify that form. Reload the page and try again.',
+            });
+        }
+        try {
+            await postContactToSlack(config.contactSlackWebhookUrl, buildContactMessage({
+                name: body.name.trim(),
+                email: body.email.trim(),
+                topic: body.topic ?? 'other',
+                message: body.message.trim(),
+            }));
+        }
+        catch (err) {
+            // The submitter's words only exist in the request they just made, so a failure
+            // here loses them. Log enough to reconstruct the message by hand, and tell the
+            // visitor plainly that it did not send rather than showing a success screen over
+            // a dropped message.
+            // ⚠ `from:`, NEVER `name:`. Pino treats `name` as the LOGGER's name, so a `name`
+            // key here is swallowed into the log prefix — the line came out as
+            // `ERROR (Sam Okafor/19949)` with the submitter's name where the process name
+            // belongs and no `name` field in the body at all. Observed, not theorised.
+            req.log.error({ err, from: body.name, email: body.email, topic: body.topic, message: body.message }, 'contact form: delivery FAILED — the message is in this log line and nowhere else');
+            return reply.code(502).send({
+                error: 'delivery_failed',
+                message: 'That did not send. Please try again in a minute.',
+            });
+        }
+        req.log.info({ topic: body.topic }, 'contact form: delivered');
+        return { ok: true };
+    });
+}
+//# sourceMappingURL=contact.js.map

package/dist/api/routes/daily-brief.js

@@ -0,0 +1,58 @@
+import { getDailyBriefCounts, getDailyBriefEntry } from '../../db/daily-brief.js';
+import { listWorkspaces, resolveWorkspaceScope } from '../../db/queries.js';
+import { accountIdOf } from '../plugins/auth.js';
+// The daily brief (plan P3.1/N1 + the P3.3/N5 roll-up) — CORE / FREE, counts only. The Pro
+// narration lives entirely on the plugin's synthesis seam (`kind: 'brief'` / `'rollup'`) and is
+// fetched separately by the SPA; this route never touches AI and never carries cost/money.
+//
+// `?workspace=` is the ONE scope parameter (resolveWorkspaceScope: absent/unknown/foreign →
+// Default, never a 404) and the resolved id is echoed. `?rollup=1` additionally returns one
+// count line per OTHER workspace of the account (the "Elsewhere" strip line) — workspaces are
+// few, and each line rides the fold's 5-min TTL cache (db/daily-brief.ts), so the loop is
+// bounded and mostly cache hits. Defensively capped all the same.
+//
+// ⚠ THE TWO LINES ARE NOT SERVED THE SAME WAY, ON PURPOSE. The ACTIVE workspace's `counts` go
+// through `getDailyBriefEntry`, which computes them FRESH: every one of those figures is the
+// count of a list a strip line CLICKS INTO (`myTurn` is literally the my_turn card count that
+// GET /api/attention recomputes per request), and a cached headline over a live list is a number
+// the click disproves — which is exactly the "5 items need your review" over a board of 3 this
+// split fixes. The `?rollup=1` lines describe OTHER workspaces and keep the cache: clicking one
+// switches workspace, which re-fetches THAT workspace's fresh brief before any list is shown.
+//
+// ⚠ `generatedAt` therefore stamps the COUNTS (== this request); the `botAnomalies` array inside
+// them keeps its own ≤5-min window (an 84-day events scan behind no clickable list). Two
+// computation times in one response, deliberately — see db/daily-brief.ts's header before
+// "simplifying" either half.
+//
+// Rate tier: `search` (60/min) — a DELIBERATE entry in tierFor, not the blanket read bucket:
+// one call folds the insights cards, the resolve backlog and the trunk snapshot (× workspace
+// count under `?rollup=1`). Pinned in rate-limit.test.ts.
+const ROLLUP_WORKSPACE_CAP = 12;
+export async function dailyBriefRoutes(app) {
+    app.get('/api/daily-brief', async (req) => {
+        const q = req.query;
+        const accountId = accountIdOf(req);
+        const scope = await resolveWorkspaceScope(accountId, q.workspace);
+        const { counts, computedAt } = await getDailyBriefEntry(accountId, scope.workspaceId);
+        const resp = {
+            workspaceId: scope.workspaceId,
+            counts,
+            generatedAt: computedAt.toISOString(),
+        };
+        if (q.rollup === '1' || q.rollup === 'true') {
+            const others = (await listWorkspaces(accountId))
+                .filter((w) => w.id !== scope.workspaceId)
+                .slice(0, ROLLUP_WORKSPACE_CAP);
+            if (others.length > 0) {
+                const lines = await Promise.all(others.map(async (w) => ({
+                    workspaceId: w.id,
+                    name: w.name,
+                    counts: await getDailyBriefCounts(accountId, w.id),
+                })));
+                resp.rollup = lines;
+            }
+        }
+        return resp;
+    });
+}
+//# sourceMappingURL=daily-brief.js.map

package/dist/api/routes/flow.js

@@ -0,0 +1,71 @@
+import { FLOW_DEFAULT_WINDOW_DAYS, getFlowCourts } from '../../db/pr-intervals.js';
+import { resolveWorkspaceScope } from '../../db/queries.js';
+import { accountIdOf } from '../plugins/auth.js';
+import { entitledProCapabilities } from '../../pro/contract.js';
+// GET /api/flow-findings — "Chronology": the COURT LEDGER for a workspace.
+//
+// PAID, on the `periodReports` capability. Deterministic all the same — no model, no plugin call,
+// no GitHub call — and every sentence it returns is still templated in db/pr-intervals.ts; what it
+// costs is DB work, not tokens.
+//
+// ⚠ IT RIDES `periodReports` RATHER THAN A CAPABILITY OF ITS OWN, deliberately. Chronology and the
+// period report answer the same question at two grains — "where did a completed stretch of work
+// actually go" — and a fifteenth member on `ProCapabilities` would mean bumping `apiVersion` across
+// four literals in two repositories (host contract, plugin index, plugin contract-types, the
+// runtime gate in pro/bind.ts) to gate one route. One flag, no wire change, no plugin edit.
+//
+// ⚠ THE GATE IS A ROUTING DECISION AND MUST STAY ONE. `getFlowCourts` reads no capability and takes
+// no flag: `verify:isolation` calls that fold DIRECTLY — no request, no account row, just the ids
+// it is handed — and the day entitlement is threaded into the engine is the day every one of those
+// cross-tenant assertions needs an account to run. (The `[7, 90]` window clamp is the mirror case:
+// it lives in the ENGINE so a second caller cannot skip it, while this check lives HERE so the
+// engine stays testable.)
+//
+// ⚠ THE SPA MUST GATE `useFlowFindings`' `enabled` ON THE SAME FLAG (it does). This route is
+// POLLED — the panel refetches every five minutes — so an ungated hook against a 402 is a request
+// every five minutes, per mounted pane, forever, and the panel renders "Could not load this
+// workspace's flow.": an ERROR where the truth is a paywall, which is the worst of both. The
+// unentitled SPA issues no request at all and paints the locked pane instead.
+//
+// `?workspace=<int>` is THE scope parameter and goes through `resolveWorkspaceScope`: absent,
+// unparseable, unknown or ANOTHER TENANT'S id all resolve to the account's DEFAULT workspace —
+// never a 404, so the route is not an existence oracle. The resolved id is echoed on the response
+// so a client can correct a stale bookmark.
+//
+// `?days=<int>` is the window, default 30. The engine CLAMPS it to [7, 90] rather than trusting
+// it: below seven days a median rests on three observations, and above ninety the retroactive
+// COVERAGE BIAS dominates (docs/PERIOD-REPORTING.md — a workspace that onboarded repos over the
+// span shows a "trend" that is entirely onboarding). `coverage` rides every response for the same
+// reason. The clamp lives in the engine, not here, so a future second caller cannot skip it.
+//
+// Rate tier: `search` (60/min), a DELIBERATE entry in `tierFor` and pinned in rate-limit.test.ts.
+// It is DB-only, but "this route is DB-only" is exactly the sentence that file exists to distrust:
+// one call runs the lane resolver and then FOUR chunked action scans (reviews, review comments,
+// conversation comments, commits) across every pull request merged in the window — the same shape
+// of cost that put `GET /api/attention` and `GET /api/daily-brief` on this bucket.
+export async function flowRoutes(app) {
+    app.get('/api/flow-findings', async (req, reply) => {
+        // The same entitlement view /api/me hands the SPA and the /api/pro/* 402 gate mirrors, so the
+        // tab's locked pane and this status code can never disagree about one account: a local account
+        // is entitled whenever the bound plugin advertises the capability, a free cloud account gets
+        // the 402. `!req.account` cannot happen in the running app (local synthesizes one, cloud 401s
+        // first) — it is here so a bare test harness fails closed rather than open.
+        //
+        // Ahead of `resolveWorkspaceScope` on purpose: an unentitled caller does no DB work, and the
+        // 402 is identical for every `?workspace=` value, so the gate cannot be read as an oracle for
+        // which workspaces exist.
+        if (!req.account || !entitledProCapabilities(req.account).periodReports) {
+            reply.status(402);
+            return { error: 'pro required' };
+        }
+        const q = req.query;
+        const accountId = accountIdOf(req);
+        const scope = await resolveWorkspaceScope(accountId, q.workspace);
+        // A garbage `?days=` is the DEFAULT, not a 400: this is a dashboard parameter carried in a
+        // bookmark, and the same "never an error out of a scope hint" rule `?workspace=` follows.
+        const parsed = q.days == null ? Number.NaN : Number.parseInt(q.days, 10);
+        const days = Number.isInteger(parsed) && parsed > 0 ? parsed : FLOW_DEFAULT_WINDOW_DAYS;
+        return getFlowCourts(accountId, scope, days);
+    });
+}
+//# sourceMappingURL=flow.js.map

package/dist/api/routes/health.js

@@ -0,0 +1,7 @@
+export async function healthRoutes(app) {
+    app.get('/api/health', async () => ({
+        status: 'ok',
+        time: new Date().toISOString(),
+    }));
+}
+//# sourceMappingURL=health.js.map

package/dist/api/routes/insights.js

@@ -0,0 +1,200 @@
+import { getInsights, getRepoAnalytics, getWorkspaceMetricsDetail, getWorkspaceMetricsForScope, resolveWorkspaceScope, } from '../../db/queries.js';
+import { getWorkspaceRepoActivity } from '../../db/repo-activity.js';
+import { buildPendingBoard } from '../../db/pending-tabs.js';
+import { PR_LIVENESS_MAX_IDS, sweepPrLiveness, } from '../../sync/pr-liveness-sweep.js';
+import { accountIdOf } from '../plugins/auth.js';
+// The liveness body. `maxItems` is a coarse guard only — the real cap is applied in the handler
+// AFTER de-duplication (a board legitimately renders several cards for one PR), and it 400s
+// rather than truncating.
+const livenessSchema = {
+    querystring: {
+        type: 'object',
+        properties: { workspace: { type: 'string' } },
+    },
+    body: {
+        type: 'object',
+        required: ['prIds'],
+        additionalProperties: false,
+        properties: {
+            prIds: {
+                type: 'array',
+                items: { type: 'integer', minimum: 1 },
+                minItems: 1,
+                maxItems: 400,
+            },
+        },
+    },
+};
+function parseIntList(raw) {
+    if (!raw)
+        return null;
+    const ids = raw
+        .split(',')
+        .map((s) => Number.parseInt(s.trim(), 10))
+        .filter((n) => Number.isFinite(n));
+    return ids.length > 0 ? ids : null;
+}
+export async function insightsRoutes(app) {
+    // Per-repo sprint stats for the Insights panel. Scoped to the account; `repoIds` narrows to the
+    // repos the CALLER names. NOT workspace-scoped: it is a per-repo snapshot the caller already
+    // names its repos for, so there is no scope for a workspace to decide.
+    app.get('/api/insights', async (req) => {
+        const q = req.query;
+        return getInsights({
+            accountId: accountIdOf(req),
+            repoIds: parseIntList(q.repoIds),
+        });
+    });
+    // Workspace flow-metric header (DORA-ish tiles + trend charts) — CORE/free. It sits under the
+    // "Flow metrics" heading on the REPORTS rail entry, not the Feed: a workspace-wide survey on top
+    // of a chronological stream pushed the feed two screens down, and it is precisely why the Reports
+    // entry is ungated on every tier.
+    //
+    // `?workspace=<id>` is the ONE scope parameter: `resolveWorkspaceScope` resolves an absent,
+    // unparseable, unknown or foreign id to the account's DEFAULT workspace (never a 404 — every id
+    // yields the same response shape, so it is not an existence oracle, and the resolved id is always
+    // one the caller owns). Its `repoIds` are that workspace's membership, and `[]` — a workspace
+    // with no repos — is a legal state that yields `metrics: null`, NOT "every repo in the account".
+    // NO `narrow` is passed: Reports covers every repo in the workspace (the repo picker is
+    // Timeline-only), so this route takes no `?repoIds=` and must not gain one.
+    //
+    // It also carries `repoActivity` — the "where is the work happening?" per-repo breakdown under
+    // the same heading. RIDING THIS RESPONSE RATHER THAN A ROUTE OF ITS OWN IS THE DECISION: it is
+    // the same scope resolved once, the same 14-day window, painted in the same section by the same
+    // component, and it multiplies by nothing (two indexed scans plus the lane resolver's fixed
+    // handful), so `/api/workspace-metrics` keeps the `read` fall-through that api/plugins/
+    // rate-limit.ts records for it. A second route would have re-resolved the scope, doubled the
+    // round trips for one panel, and needed a tier decision to say the same thing.
+    app.get('/api/workspace-metrics', async (req) => {
+        const q = req.query;
+        const accountId = accountIdOf(req);
+        const scope = await resolveWorkspaceScope(accountId, q.workspace);
+        const [metrics, repoActivity] = await Promise.all([
+            getWorkspaceMetricsForScope(accountId, scope.repoIds),
+            getWorkspaceRepoActivity(accountId, scope, Date.now()),
+        ]);
+        // `workspaceId` is the scope echo every scoped response owes the client (docs/API.md) — this
+        // route was the one that never sent it, so a SPA holding a stale `?workspace=` had no way to
+        // learn it had been resolved to Default.
+        return {
+            metrics,
+            workspaceId: scope.workspaceId,
+            ...(repoActivity != null ? { repoActivity } : {}),
+        };
+    });
+    // The PR lists behind each flow-metric tile (the tile drill-down) — also CORE/free, so a Feed
+    // tile opens the same drill-down for everyone. Mirrors the Pro route's `{enabled, detail}` shape
+    // (enabled always true here). Same workspace resolution as its sibling above.
+    app.get('/api/workspace-metrics/detail', async (req) => {
+        const q = req.query;
+        const accountId = accountIdOf(req);
+        const scope = await resolveWorkspaceScope(accountId, q.workspace);
+        const detail = await getWorkspaceMetricsDetail(accountId, undefined, scope.repoIds);
+        return { enabled: true, detail };
+    });
+    // (GET /api/workspace-metrics/compare was DELETED with the "Compare workspaces" rail entry —
+    // cross-workspace comparison now lives inside Reports as the plugin-served "By workspace" axis,
+    // which rides the window-pure getPeriodMetricsForWorkspaces seam instead of the snapshot
+    // WorkspaceMetrics matrix.)
+    // The attention cards (your turn / red builds that are yours / stalled reviews / untouched
+    // threads / reviewer load / needs-a-reviewer / ready-to-land / behind-trunk) — CORE/free (the
+    // same cards Pro Insights computes in core getWorkspaceInsights), for the **Pending** rail
+    // entry. The bot cards are excluded (they live in the free Bots console).
+    //
+    // SERVED AS SIX TABS (`db/pending-tabs.ts`), each a scored list with its uncapped count — My
+    // turn grouped by the reader's type order and Dependencies by kind (security, then bumps) — free
+    // on every tier. The rank is code, with the reader's weights; only the Pro plan's NARRATION is
+    // paid.
+    //
+    // ⚠ THE TABS ARE AN ALLOW-LIST (`PENDING_TABS`), so a NEW InsightKind reaches this board only
+    // once it is given a tab — otherwise it is folded, counted and never listed. pending-tabs.test.ts
+    // fails when a non-bot kind has no tab, rather than letting it vanish quietly.
+    app.get('/api/attention', async (req) => {
+        const q = req.query;
+        // THE ONE FOLD (`buildPendingBoard`, db/pending-tabs.ts) — the Pro Slack digest reads the same
+        // function through `ProHostQueries.getPendingBoard`, so the two cannot drift. `live: true` is
+        // THIS route only: failing-check names on red cards (the brief, the work plan and the Pro
+        // payloads render no names, and must not pay for them or hash them) and suggested reviewers
+        // for the top "Needs a reviewer" cards.
+        const { workspaceId: _ws, ...board } = await buildPendingBoard(accountIdOf(req), q.workspace, {
+            live: true,
+        });
+        return board;
+    });
+    // POST /api/attention/liveness — THE BOARD'S ONE GITHUB QUESTION.
+    //
+    // The route above is DB-only and must stay that way: it is the board's paint path, and a
+    // GitHub call inside it would be the 200-calls-to-render-fifty-cards failure the board exists
+    // to avoid. This is its sibling — one batched `nodes(ids:)` sweep for the WHOLE board, so a PR
+    // merged by somebody else stops being a card within seconds instead of within an adaptive
+    // bucket (2-15 min). Cost is 2 GraphQL points per sweep, measured; the mechanics and the
+    // measured wall-time cliff that forces two passes are in sync/pr-liveness-sweep.ts and
+    // github/queries.ts's PR_LIVENESS_NODES_QUERY header.
+    //
+    // ⚠ IT RETURNS COUNTS, NEVER CARDS. `changed > 0` tells the SPA to refetch the board and the
+    // brief TOGETHER; it must never splice a card out locally (that breaks `capFor`'s
+    // `shown === count` guard and silently deletes the cap disclosure). Keeping cards out of this
+    // response is what makes that structural rather than a rule someone has to remember.
+    //
+    // ⚠ A POST WITH A GET'S COST, deliberately: the id list is a body (a query string of 90 ids is
+    // a header-size question nobody should have), and a POST puts it behind the cross-origin guard
+    // in cloud. That is the `POST /api/reactions/lookup` shape exactly, and it takes the same
+    // `prDetail` tier — spelled as an EXACT match in tierFor, because nothing else would catch it.
+    //
+    // Rate-limit PAUSES are reported, never thrown: `paused` is a fact about the tenant's GitHub
+    // window, and the board renders its synced rows through it.
+    app.post('/api/attention/liveness', { schema: livenessSchema }, async (req, reply) => {
+        const q = req.query;
+        const { prIds } = req.body;
+        const accountId = accountIdOf(req);
+        // ⚠ 400 ON OVER-CAP, NEVER A TRUNCATION (the peer benchmark's `?cells=` rule): a caller
+        // whose tail was silently dropped believes its whole board was freshened. `additionalItems`
+        // in the schema cannot express "dedupe then count", so the cap is checked here after the
+        // dedupe the client is asked to do anyway.
+        const unique = [...new Set(prIds)];
+        if (unique.length > PR_LIVENESS_MAX_IDS) {
+            return reply.code(400).send({
+                error: 'TooManyIds',
+                message: `At most ${PR_LIVENESS_MAX_IDS} PR ids per liveness sweep (received ${unique.length}).`,
+            });
+        }
+        // `?workspace=` is THE scope parameter — absent/unknown/foreign resolves to the account's
+        // DEFAULT workspace, never a 404, and the resolved id is echoed. Its `repoIds` are what
+        // bound the id resolve below, so a PR the caller owns in ANOTHER workspace is not swept
+        // here: the board that asked is the board that gets refreshed.
+        const scope = await resolveWorkspaceScope(accountId, q.workspace);
+        const swept = await sweepPrLiveness({
+            accountId,
+            repoIds: scope.repoIds,
+            prIds: unique,
+            log: req.log,
+        });
+        // null = a sweep for this account is already in flight (two tabs, or an interval overlapping
+        // its own focus refetch). A no-op report, not an error: the running sweep is about to
+        // produce this very answer, and the caller's next tick will see its effect.
+        if (!swept) {
+            return {
+                workspaceId: scope.workspaceId,
+                checked: 0,
+                mergeStateChecked: 0,
+                changed: 0,
+                leftOpenSet: 0,
+                paused: null,
+            };
+        }
+        return { workspaceId: scope.workspaceId, ...swept };
+    });
+    // Heavier per-repo analytics for the drill-down chart panel — loaded on demand.
+    // Ownership-scoped: a repo not owned by the account 404s.
+    app.get('/api/insights/:repoId/analytics', async (req, reply) => {
+        const { repoId } = req.params;
+        const id = Number.parseInt(repoId, 10);
+        const data = Number.isFinite(id)
+            ? await getRepoAnalytics(accountIdOf(req), id)
+            : null;
+        if (!data)
+            return reply.code(404).send({ error: 'repo not found' });
+        return data;
+    });
+}
+//# sourceMappingURL=insights.js.map