toolroll 0.5.0

package/dist/webhooks.js

@@ -0,0 +1,283 @@
+import { loadDiscordCredentials } from "./discord-api.js";
+import { loadTeamsCredentials } from "./teams-api.js";
+import { loadSlackCredentials } from "./slack-api.js";
+/**
+ * Legacy notification-only webhooks. Interactive Slack and Discord adapters
+ * have their own paired identities and reuse the shared action engine.
+ * A configured interactive adapter suppresses its legacy webhook delivery.
+ *
+ * The webhook URL is a CREDENTIAL (anyone holding it can post to the
+ * channel): it lives in a 0600 file beside the database or in the
+ * environment, is never a database column, and never appears in logs or
+ * errors — the same rules as the bot token, for the same reasons.
+ */
+import { readFileSync, writeFileSync, chmodSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { envValue } from "./names.js";
+export const SLACK_ENV = "TOOLROLL_SLACK_WEBHOOK";
+export const DISCORD_ENV = "TOOLROLL_DISCORD_WEBHOOK";
+export const CONSOLE_URL_ENV = "TOOLROLL_CONSOLE_URL";
+export const PRIMARY_ENV = "TOOLROLL_MESSAGING_PRIMARY";
+/** How long one delivery claim protects a row from a second sender. */
+const DELIVERY_CLAIM_MS = 60_000;
+const POST_TIMEOUT_MS = 10_000;
+const FILE_OF = {
+    slack: "slack-webhook",
+    discord: "discord-webhook",
+};
+const CONSOLE_FILE = "console-url";
+const PRIMARY_FILE = "messaging-primary";
+export const MESSAGING_CHANNELS = ["telegram", "slack", "discord", "teams"];
+export function isMessagingChannel(value) {
+    return MESSAGING_CHANNELS.includes(value);
+}
+/** The shapes each platform hands out; anything else is probably a paste error. */
+const URL_SHAPE = {
+    slack: /^https:\/\/hooks\.slack\.com\/\S+$/,
+    discord: /^https:\/\/(canary\.|ptb\.)?discord\.com\/api\/webhooks\/\S+$/,
+};
+export function saveWebhook(dir, kind, url) {
+    if (!URL_SHAPE[kind].test(url.trim())) {
+        return { ok: false, message: `that does not look like a ${kind} webhook URL — paste it exactly as the platform issued it` };
+    }
+    const file = join(dir, FILE_OF[kind]);
+    writeFileSync(file, `${url.trim()}\n`, { mode: 0o600 });
+    chmodSync(file, 0o600);
+    return { ok: true };
+}
+export function clearWebhook(dir, kind) {
+    try {
+        rmSync(join(dir, FILE_OF[kind]));
+    }
+    catch {
+        // Already absent is cleared.
+    }
+}
+export function saveConsoleUrl(dir, url) {
+    // Parsed, not pattern-matched (attended review, finding 11): the stored
+    // value becomes every deep link's base, so userinfo, queries, and
+    // fragments are refused rather than smuggled into each link.
+    let parsed;
+    try {
+        parsed = new URL(url.trim());
+    }
+    catch {
+        return { ok: false, message: "the console URL is the address the links open — http(s)://host[:port]" };
+    }
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+        return { ok: false, message: "the console URL must be http or https" };
+    }
+    if (parsed.username !== "" || parsed.password !== "") {
+        return { ok: false, message: "the console URL must not carry credentials — they would ride every link" };
+    }
+    if (parsed.search !== "" || parsed.hash !== "") {
+        return { ok: false, message: "the console URL is a base address — no query or fragment" };
+    }
+    const normalized = `${parsed.origin}${parsed.pathname.replace(/\/+$/, "")}`;
+    const file = join(dir, CONSOLE_FILE);
+    writeFileSync(file, `${normalized}\n`, { mode: 0o600 });
+    return { ok: true };
+}
+function readTrimmed(path) {
+    try {
+        const raw = readFileSync(path, "utf8").trim();
+        return raw === "" ? null : raw;
+    }
+    catch {
+        return null;
+    }
+}
+/** Every configured mirror. Environment wins over files, like the bot token. */
+export function loadWebhookTargets(env, dir) {
+    const targets = [];
+    const slack = envValue(env, "SLACK_WEBHOOK") ?? readTrimmed(join(dir, FILE_OF.slack));
+    const discord = envValue(env, "DISCORD_WEBHOOK") ?? readTrimmed(join(dir, FILE_OF.discord));
+    if (slack !== null && slack !== undefined && slack !== "")
+        targets.push({ kind: "slack", url: slack });
+    if (discord !== null && discord !== undefined && discord !== "")
+        targets.push({ kind: "discord", url: discord });
+    return targets;
+}
+/** The operator's explicit choice of which service carries the pages. */
+export function savePrimary(dir, channel) {
+    writeFileSync(join(dir, PRIMARY_FILE), `${channel}\n`, { mode: 0o600 });
+}
+export function loadPrimary(env, dir) {
+    const configured = envValue(env, "MESSAGING_PRIMARY") ?? readTrimmed(join(dir, PRIMARY_FILE));
+    return configured !== undefined && configured !== null && isMessagingChannel(configured) ? configured : null;
+}
+/**
+ * Which service actually carries the pages, and whether that was chosen or
+ * merely fell out of what happens to be configured. Explicit choice wins
+ * WHEN its channel is actually configured (a primary pointing at nothing
+ * falls through rather than silencing every page); otherwise Telegram if
+ * present (it can hold buttons), else the mirrors. `implicit` is the flag
+ * every status surface uses to say "you have several — pick one".
+ */
+export function effectivePrimary(env, dir, telegramConfigured) {
+    const targets = loadWebhookTargets(env, dir);
+    const configured = [
+        ...(telegramConfigured ? ["telegram"] : []),
+        ...(loadSlackCredentials(dir) !== null ? ["slack"] : []),
+        ...(loadDiscordCredentials(dir) !== null ? ["discord"] : []),
+        ...(loadTeamsCredentials(dir) !== null ? ["teams"] : []),
+        ...targets.map(one => one.kind).filter(kind => (kind !== "slack" || loadSlackCredentials(dir) === null) && (kind !== "discord" || loadDiscordCredentials(dir) === null)),
+    ];
+    const chosen = loadPrimary(env, dir);
+    if (chosen !== null && configured.includes(chosen)) {
+        return { channel: chosen, implicit: false, configured };
+    }
+    if (telegramConfigured)
+        return { channel: "telegram", implicit: configured.length > 1, configured };
+    const fallback = configured[0] ?? null;
+    return { channel: fallback, implicit: configured.length > 1, configured };
+}
+export function loadConsoleUrl(env, dir) {
+    const configured = envValue(env, "CONSOLE_URL") ?? readTrimmed(join(dir, CONSOLE_FILE));
+    return configured === undefined || configured === null || configured === "" ? null : configured.replace(/\/+$/, "");
+}
+/** A dotted IPv4 that names this machine or no machine: loopback, unspecified. */
+function isLocalIpv4(address) {
+    return /^127\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(address) || address === "0.0.0.0";
+}
+/**
+ * Names a browser cannot leave this machine with: never a phone destination.
+ * The URL parser hands back a canonical hostname, so an IPv6 literal arrives
+ * compressed — `::1`, `::`, and an embedded IPv4 as two hex groups
+ * (`::ffff:7f00:1` is 127.0.0.1 mapped; `::7f00:1` the deprecated
+ * compatible form) — and those groups are decoded and judged as the IPv4
+ * they carry.
+ */
+function isLoopbackHost(hostname) {
+    // A DNS root dot changes the spelling, not the destination (localhost.).
+    const host = hostname.replace(/^\[|\]$/g, "").replace(/\.$/, "").toLowerCase();
+    if (host === "localhost" || host.endsWith(".localhost") || host === "::1" || host === "::" || isLocalIpv4(host))
+        return true;
+    const embedded = /^::(?:ffff:)?([0-9a-f]{1,4}):([0-9a-f]{1,4})$/.exec(host);
+    if (embedded === null)
+        return false;
+    const high = parseInt(embedded[1], 16), low = parseInt(embedded[2], 16);
+    return isLocalIpv4(`${high >> 8}.${high & 255}.${low >> 8}.${low & 255}`);
+}
+/**
+ * The origin a phone link may open, or null. The SAME console-url setting
+ * the mirrors use — read again on every call, never cached, so a changed or
+ * removed setting stops the next link — held to a stricter shape than a
+ * mirror link: exactly an https origin (no credentials, path, query,
+ * fragment), not loopback, and, when the console this process co-hosts
+ * states its own `--public-url`, exactly that origin. A model, a Host
+ * header or a proposal field never supplies it, and nothing here probes
+ * the address: a valid shape is a place to send a person, not a promise
+ * that it answers.
+ */
+export function phoneOrigin(env, dir, options = {}) {
+    const configured = loadConsoleUrl(env, dir);
+    if (configured === null)
+        return null;
+    let parsed;
+    try {
+        parsed = new URL(configured);
+    }
+    catch {
+        return null;
+    }
+    if (parsed.protocol !== "https:" || parsed.username !== "" || parsed.password !== "" || parsed.search !== "" || parsed.hash !== "")
+        return null;
+    if (parsed.pathname !== "/" && parsed.pathname !== "")
+        return null;
+    if (parsed.hostname === "" || isLoopbackHost(parsed.hostname))
+        return null;
+    if (options.serverOrigin !== undefined && options.serverOrigin !== null) {
+        let server;
+        try {
+            server = new URL(options.serverOrigin);
+        }
+        catch {
+            return null;
+        }
+        if (server.origin !== parsed.origin)
+            return null;
+    }
+    return parsed.origin;
+}
+/** Where in the console this notification wants a person. */
+export function linkFor(consoleUrl, notification) {
+    if (consoleUrl === null)
+        return null;
+    const decision = /^decision:(\d+)$/.exec(notification.dedupeKey);
+    if (decision !== null)
+        return `${consoleUrl}/d/${decision[1]}`;
+    // Everything else that wants a person is triaged where acting lives.
+    return `${consoleUrl}/next`;
+}
+/**
+ * One notification, one platform. The payloads are the simplest thing each
+ * platform documents; the console link is the call to action, because the
+ * message is a mirror and the UI is the instrument.
+ */
+export async function postWebhook(target, notification, link, fetcher = fetch) {
+    const lines = [notification.subject, "", notification.body];
+    const body = target.kind === "slack"
+        ? {
+            text: [
+                `*${notification.subject}*`,
+                notification.body,
+                ...(link === null ? [] : [`<${link}|open in Toolroll>`]),
+            ].join("\n"),
+        }
+        : {
+            content: [
+                `**${notification.subject}**`,
+                notification.body,
+                ...(link === null ? [] : [link]),
+            ].join("\n").slice(0, 1900),
+        };
+    void lines;
+    try {
+        const response = await fetcher(target.url, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify(body),
+            signal: AbortSignal.timeout(POST_TIMEOUT_MS),
+        });
+        if (!response.ok) {
+            // Status only — the URL is a credential and never rides an error.
+            return { ok: false, error: `${target.kind} answered ${response.status}` };
+        }
+        return { ok: true };
+    }
+    catch (error) {
+        const said = error instanceof Error ? error.name : "failed";
+        return { ok: false, error: `${target.kind} delivery ${said}` };
+    }
+}
+/**
+ * Deliver every pending notification to every configured mirror, through
+ * the SAME claim/finalize discipline as every other deliverer — so a
+ * webhook pass and a Telegram bridge can never both own one row. This
+ * pass runs when Telegram is NOT configured; with a paired Telegram chat,
+ * Telegram remains the delivery channel (it can carry buttons) and these
+ * mirrors stay silent rather than double-paging every phone.
+ */
+export async function webhookPass(store, options) {
+    const clock = options.clock ?? (() => new Date());
+    const owner = options.owner ?? `webhooks-${Math.floor(clock().getTime() / 1000)}`;
+    const report = { sent: 0, problems: [] };
+    if (options.targets.length === 0)
+        return report;
+    const claimed = store.claimDeliveries(owner, DELIVERY_CLAIM_MS, clock());
+    for (const row of claimed) {
+        const link = linkFor(options.consoleUrl, row);
+        const outcomes = await Promise.all(options.targets.map(target => postWebhook(target, row, link, options.fetcher ?? fetch)));
+        const failed = outcomes.filter(one => !one.ok);
+        const outcome = failed.length === 0
+            ? { ok: true, receipt: options.targets.map(one => one.kind).join("+") }
+            : { ok: false, error: failed.map(one => (one.ok ? "" : one.error)).join("; ") };
+        const finalized = store.finalizeDelivery(row.id, owner, outcome, clock());
+        if (outcome.ok && finalized)
+            report.sent++;
+        if (!outcome.ok)
+            report.problems.push(`notification ${row.id}: ${outcome.error}`);
+    }
+    return report;
+}

package/dist/work-index.d.ts

@@ -0,0 +1,68 @@
+import { type Store, type TaskState } from './store.js';
+import type { AssignmentSnapshot } from './assignment.js';
+import type { WorkAction, WorkSummaryAccess } from './work-summary.js';
+import type { WorkStatus, WorkView } from './workspace-ui.js';
+export type WorkIndexCounts = Record<WorkView, number>;
+export type WorkIndexItem = {
+    rootId: string;
+    activeTaskId: string;
+    title: string;
+    repo: string | null;
+    state: TaskState;
+    assignmentState: AssignmentSnapshot['state'];
+    createdAt: string;
+    updatedAt: string;
+    versionCount: number;
+    earlierActiveCount: number;
+    familyProblem: string | null;
+    liveRunId: number | null;
+    unfinishedRunId: number | null;
+    resultRunId: number | null;
+    resultTaskId: string | null;
+    resultOutcome: string | null;
+    publicationUrl: string | null;
+    status: WorkStatus;
+    primaryAction: WorkAction | null;
+    completion: {
+        actor: string;
+        at: string;
+        digest: string;
+    } | null;
+    evidence: 'recorded';
+};
+export type WorkIndexOptions = {
+    view?: WorkView;
+    limit?: number;
+    cursor?: string | null;
+    project?: string | null;
+    state?: TaskState;
+    leadId?: string;
+};
+export type WorkIndexPage = {
+    items: WorkIndexItem[];
+    totals: WorkIndexCounts;
+    projects: WorkProjectCounts[];
+    nextCursor: string | null;
+    limit: number;
+    view: WorkView;
+};
+export type WorkProjectCounts = {
+    repo: string | null;
+    totals: WorkIndexCounts;
+    queued: number;
+    doneRecently: number;
+};
+export declare const WORK_INDEX_PAGE_LIMIT = 40;
+export declare const WORK_INDEX_MAX_LIMIT = 100;
+export declare class WorkIndexCursorError extends Error {
+    constructor();
+}
+/** A single SQLite statement gives rows and exact totals one read snapshot.
+ * Completion is a recorded acknowledgment of the latest run/scope/family by
+ * its current lead or an admitted approver, invalidated by newer source facts.
+ * Its historical receipt hash also binds disk state, which is deliberately
+ * rechecked only on opening/acting. This query grants no completion authority.
+ * Project counters share the page's admitted project/state filter.
+ * Cursors bind the admitted scope, project and view, never broaden access. */
+export declare function workIndexPage(store: Store, now: Date, access: WorkSummaryAccess, options?: WorkIndexOptions): WorkIndexPage;
+export declare function workCountsByProject(store: Store, now: Date, access: WorkSummaryAccess): WorkProjectCounts[];