toolroll 0.9.36 → 0.9.37

package/dist/contracts/discord-callback.js

@@ -0,0 +1,34 @@
+/**
+ * A Discord button tap (discord-chat.ts `receiveDiscord`): the component interaction Discord sends over the gateway,
+ * and the button data Toolroll put on it. The interaction is Discord's, so fields Toolroll doesn't read are ignored;
+ * the button's `custom_id` (`so_` and a one-time token) is Toolroll's. A tap from the paired person on Toolroll's own
+ * message whose button can't be read is answered with why (`data.custom_id: not a Toolroll button`), and nothing is done.
+ */
+import { z } from "zod";
+import { parseContract } from "./contract.js";
+const user = z.object({ id: z.string() });
+/** The interaction around a tap (type 3: a message component): the app, the person, the channel, the message. */
+export const discordComponentInteractionSchema = z.object({
+    type: z.literal(3),
+    id: z.string(),
+    application_id: z.string(),
+    channel_id: z.string(),
+    guild_id: z.string().optional(),
+    channel: z.object({ type: z.int() }),
+    member: z.object({ user }).optional(),
+    user: user.optional(),
+    message: z.object({ id: z.string(), channel_id: z.string(), author: user }),
+    data: z.object({ custom_id: z.unknown().optional() }),
+});
+/** Toolroll's button data: `so_` and a one-time token. */
+export const discordButtonSchema = z.object({
+    custom_id: z.string().regex(/^so_[a-f0-9]{32}$/, { error: "not a Toolroll button" }),
+});
+export function readDiscordComponentInteraction(body) {
+    return parseContract(discordComponentInteractionSchema, body);
+}
+/** The tapped button's one-time token. */
+export function readDiscordButtonToken(interaction) {
+    const read = parseContract(z.object({ data: discordButtonSchema }), { data: interaction.data });
+    return read.ok ? { ok: true, value: read.value.data.custom_id.slice(3) } : read;
+}

package/dist/contracts/flow-card.d.ts

@@ -0,0 +1,50 @@
+/**
+ * A flow card's state (docs/plans/zod-revamp.md, item 8): what the flow engine, its steps and its Send to me and
+ * Person chooses zones read and write (flow-engine.ts, flow-steps.ts, flow-send.ts), as the store keeps it in
+ * `flow_card`. Its columns are versioned by the database's own schema version; the one payload in it, what finished
+ * zones handed on (`outputs_json`), carries its own version (stage-output.ts).
+ *
+ * `flowCardSchema` is the card as read; `flowCardChangeSchema` what one update may change. Where it came from
+ * (`source_json`, written by triggers) keeps its own type in the store.
+ */
+import { z } from "zod";
+export declare const FLOW_CARD_STATES: readonly ["active", "done", "cancelled"];
+export type FlowCardState = (typeof FLOW_CARD_STATES)[number];
+export declare const flowCardSchema: z.ZodObject<{
+    id: z.ZodInt;
+    flow: z.ZodInt;
+    title: z.ZodString;
+    description: z.ZodNullable<z.ZodString>;
+    stage: z.ZodString;
+    entry: z.ZodInt;
+    state: z.ZodEnum<{
+        active: "active";
+        cancelled: "cancelled";
+        done: "done";
+    }>;
+    task: z.ZodNullable<z.ZodString>;
+    primaryTask: z.ZodNullable<z.ZodString>;
+    note: z.ZodNullable<z.ZodString>;
+    waiting: z.ZodNullable<z.ZodString>;
+    outputs: z.ZodObject<{}, z.core.$catchall<z.ZodString>>;
+    attached: z.ZodObject<{}, z.core.$catchall<z.ZodString>>;
+    createdBy: z.ZodString;
+    createdAt: z.ZodString;
+    updatedAt: z.ZodString;
+    owner: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>;
+export type FlowCardFields = z.infer<typeof flowCardSchema>;
+/** What one update of a card may change; whatever is left out stays as it is. Outputs replace the card's whole;
+ * an attachment goes with the output it belongs to. */
+export declare const flowCardChangeSchema: z.ZodObject<{
+    task: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    primaryTask: z.ZodOptional<z.ZodString>;
+    waiting: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    outputs: z.ZodOptional<z.ZodObject<{}, z.core.$catchall<z.ZodString>>>;
+    attached: z.ZodOptional<z.ZodObject<{}, z.core.$catchall<z.ZodString>>>;
+    state: z.ZodOptional<z.ZodEnum<{
+        cancelled: "cancelled";
+        done: "done";
+    }>>;
+}, z.core.$strict>;
+export type FlowCardChange = z.infer<typeof flowCardChangeSchema>;

package/dist/contracts/flow-card.js

@@ -0,0 +1,46 @@
+/**
+ * A flow card's state (docs/plans/zod-revamp.md, item 8): what the flow engine, its steps and its Send to me and
+ * Person chooses zones read and write (flow-engine.ts, flow-steps.ts, flow-send.ts), as the store keeps it in
+ * `flow_card`. Its columns are versioned by the database's own schema version; the one payload in it, what finished
+ * zones handed on (`outputs_json`), carries its own version (stage-output.ts).
+ *
+ * `flowCardSchema` is the card as read; `flowCardChangeSchema` what one update may change. Where it came from
+ * (`source_json`, written by triggers) keeps its own type in the store.
+ */
+import { z } from "zod";
+import { cardOutputsSchema } from "./stage-output.js";
+export const FLOW_CARD_STATES = ["active", "done", "cancelled"];
+export const flowCardSchema = z.strictObject({
+    id: z.int().min(1),
+    flow: z.int().min(1),
+    title: z.string(),
+    description: z.string().nullable(),
+    /** The zone it is in, and which visit to that zone this is (each move is a fresh one). */
+    stage: z.string(),
+    entry: z.int().min(1),
+    state: z.enum(FLOW_CARD_STATES),
+    /** The task its zone filed this visit, and the card's main build. */
+    task: z.string().nullable(),
+    primaryTask: z.string().nullable(),
+    /** The latest note it was sent back or replied to with ({{note}}). */
+    note: z.string().nullable(),
+    /** What it waits for, in words. */
+    waiting: z.string().nullable(),
+    /** What finished zones handed on ({{stage.…}}), and any too long to pass on, whole. */
+    outputs: cardOutputsSchema.shape.outputs,
+    attached: cardOutputsSchema.shape.attached,
+    createdBy: z.string(),
+    createdAt: z.string(),
+    updatedAt: z.string(),
+    owner: z.string().nullable(),
+});
+/** What one update of a card may change; whatever is left out stays as it is. Outputs replace the card's whole;
+ * an attachment goes with the output it belongs to. */
+export const flowCardChangeSchema = z.strictObject({
+    task: flowCardSchema.shape.task.optional(),
+    primaryTask: z.string().optional(),
+    waiting: flowCardSchema.shape.waiting.optional(),
+    outputs: flowCardSchema.shape.outputs.optional(),
+    attached: flowCardSchema.shape.attached.optional(),
+    state: z.enum(["done", "cancelled"]).optional(),
+});

package/dist/contracts/flow-send.d.ts

@@ -0,0 +1,119 @@
+/**
+ * What a "Send to me" or "Person chooses" visit sends its person (docs/plans/zod-revamp.md, item 8): worked out once
+ * per visit and kept (`flow_send.content_json`), so every chat app and the card show the same (src/flow-send.ts).
+ *
+ * - `flowSendPayloadSchema`: a send's — the title, summary, links, screenshots and a research report's items.
+ * - `flowChoosePayloadSchema`: a choice's — the same, with the options as they were offered and whether a reply is taken.
+ * - `flowChoiceAnswerSchema`: the person's answer to a choice, by whichever door it comes (chooseFlowCard).
+ *
+ * Kept before this contract (version 0), a visit's content had no `version`; it reads as the 0.9.36 reader read it:
+ * a title, a summary and a list of links make it readable, items that can't be shown are left out, and a link or
+ * option that isn't one is skipped.
+ */
+import { z } from "zod";
+import { type ContractResult } from "./contract.js";
+/** A link the message carries: a page of Toolroll's (a button) or the one outside page, a pull request. */
+export declare const flowSendLinkSchema: z.ZodUnion<readonly [z.ZodObject<{
+    label: z.ZodString;
+    path: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    label: z.ZodString;
+    url: z.ZodString;
+}, z.core.$strict>]>;
+/** One item of a research report, as the message lists it (flow-items.ts). */
+export declare const flowSendItemSchema: z.ZodObject<{
+    title: z.ZodString;
+    why: z.ZodString;
+    url: z.ZodString;
+    source: z.ZodString;
+    plug: z.ZodString;
+    shot: z.ZodNullable<z.ZodInt>;
+}, z.core.$strict>;
+export type FlowSendLink = z.infer<typeof flowSendLinkSchema>;
+export type FlowSendItem = z.infer<typeof flowSendItemSchema>;
+export declare const FLOW_SEND_VERSION = 1;
+export declare const flowChoiceOptionSchema: z.ZodObject<{
+    choice: z.ZodInt;
+    label: z.ZodString;
+}, z.core.$strict>;
+export declare const flowSendPayloadSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    title: z.ZodString;
+    from: z.ZodOptional<z.ZodString>;
+    summary: z.ZodString;
+    links: z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+        label: z.ZodString;
+        path: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        label: z.ZodString;
+        url: z.ZodString;
+    }, z.core.$strict>]>>;
+    shots: z.ZodNullable<z.ZodObject<{
+        taskId: z.ZodString;
+        run: z.ZodInt;
+    }, z.core.$strict>>;
+    items: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        title: z.ZodString;
+        why: z.ZodString;
+        url: z.ZodString;
+        source: z.ZodString;
+        plug: z.ZodString;
+        shot: z.ZodNullable<z.ZodInt>;
+    }, z.core.$strict>>>;
+}, z.core.$strict>;
+export declare const flowChoosePayloadSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    title: z.ZodString;
+    from: z.ZodOptional<z.ZodString>;
+    summary: z.ZodString;
+    links: z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+        label: z.ZodString;
+        path: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        label: z.ZodString;
+        url: z.ZodString;
+    }, z.core.$strict>]>>;
+    shots: z.ZodNullable<z.ZodObject<{
+        taskId: z.ZodString;
+        run: z.ZodInt;
+    }, z.core.$strict>>;
+    items: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        title: z.ZodString;
+        why: z.ZodString;
+        url: z.ZodString;
+        source: z.ZodString;
+        plug: z.ZodString;
+        shot: z.ZodNullable<z.ZodInt>;
+    }, z.core.$strict>>>;
+    options: z.ZodArray<z.ZodObject<{
+        choice: z.ZodInt;
+        label: z.ZodString;
+    }, z.core.$strict>>;
+    reply: z.ZodBoolean;
+}, z.core.$strict>;
+export type FlowSendPayload = z.infer<typeof flowSendPayloadSchema>;
+export type FlowChoosePayload = z.infer<typeof flowChoosePayloadSchema>;
+/** A visit's content as the console and chat apps read it: a send's, or a choice's with its options. */
+export type FlowSendContent = Omit<FlowSendPayload, "version"> & {
+    options?: FlowChoosePayload["options"];
+    reply?: boolean;
+};
+export declare function readFlowItems(raw: unknown): FlowSendItem[];
+/** Version 0: content kept before it carried `version`, in this contract's shape (what can't be read is left for the schema to refuse by path). */
+export declare function upgradeSavedSend(body: Record<string, unknown>): Record<string, unknown>;
+/** Read a visit's kept content: a choice's when it carries options, else a send's; version 0 upgraded, newer refused. */
+export declare function readFlowSendPayload(input: unknown): ContractResult<FlowSendContent>;
+/** A visit's content as it is kept: the payload of its kind, with the current version. */
+export declare function flowSendForStore(content: FlowSendContent): string;
+/** A person's answer to a choice: an option by its place (and the words and zone they saw), or a reply (`choice` null)
+ * that becomes the note for where replies go. `entry` is the visit they saw; without it, the card's current one. */
+export declare const flowChoiceAnswerSchema: z.ZodObject<{
+    card: z.ZodInt;
+    entry: z.ZodOptional<z.ZodInt>;
+    choice: z.ZodNullable<z.ZodInt>;
+    label: z.ZodOptional<z.ZodString>;
+    to: z.ZodOptional<z.ZodString>;
+    note: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>;
+export type FlowChoiceAnswer = z.infer<typeof flowChoiceAnswerSchema>;
+export declare function readFlowChoiceAnswer(input: unknown): ContractResult<FlowChoiceAnswer>;

package/dist/contracts/flow-send.js

@@ -0,0 +1,112 @@
+/**
+ * What a "Send to me" or "Person chooses" visit sends its person (docs/plans/zod-revamp.md, item 8): worked out once
+ * per visit and kept (`flow_send.content_json`), so every chat app and the card show the same (src/flow-send.ts).
+ *
+ * - `flowSendPayloadSchema`: a send's — the title, summary, links, screenshots and a research report's items.
+ * - `flowChoosePayloadSchema`: a choice's — the same, with the options as they were offered and whether a reply is taken.
+ * - `flowChoiceAnswerSchema`: the person's answer to a choice, by whichever door it comes (chooseFlowCard).
+ *
+ * Kept before this contract (version 0), a visit's content had no `version`; it reads as the 0.9.36 reader read it:
+ * a title, a summary and a list of links make it readable, items that can't be shown are left out, and a link or
+ * option that isn't one is skipped.
+ */
+import { z } from "zod";
+import { parseContract, readVersioned, versioned } from "./contract.js";
+/** A link the message carries: a page of Toolroll's (a button) or the one outside page, a pull request. */
+export const flowSendLinkSchema = z.union([
+    z.strictObject({ label: z.string(), path: z.string().regex(/^\//, { error: "must be a path in Toolroll, starting with /" }) }),
+    z.strictObject({ label: z.string(), url: z.string().regex(/^https:\/\/[^\s<>"]+$/, { error: "must be an https:// address" }) }),
+]);
+/** One item of a research report, as the message lists it (flow-items.ts). */
+export const flowSendItemSchema = z.strictObject({
+    title: z.string(),
+    why: z.string(),
+    url: z.string().regex(/^https?:\/\//, { error: "must be a web address" }),
+    /** Where the link goes, by name: "Mobbin", "Linear", "Apple". */
+    source: z.string(),
+    /** One line: how it plugs in (from the why, else the image's own caption). */
+    plug: z.string(),
+    /** The item's screenshot (its evidence id in the report's run), when it has one. */
+    shot: z.int().nullable(),
+});
+export const FLOW_SEND_VERSION = 1;
+const sendShape = {
+    /** The card's title and the step it comes from. */
+    title: z.string(),
+    /** The step it comes from, when known. */
+    from: z.string().optional(),
+    summary: z.string(),
+    links: z.array(flowSendLinkSchema),
+    /** The build's result whose screenshots go with it, when it saved any. */
+    shots: z.strictObject({ taskId: z.string(), run: z.int() }).nullable(),
+    /** After research: the report's items, numbered in this order in every message and screenshot caption. */
+    items: z.array(flowSendItemSchema).min(1).optional(),
+};
+export const flowChoiceOptionSchema = z.strictObject({ choice: z.int().min(0), label: z.string() });
+export const flowSendPayloadSchema = versioned(FLOW_SEND_VERSION, sendShape);
+export const flowChoosePayloadSchema = versioned(FLOW_SEND_VERSION, {
+    ...sendShape,
+    /** The options as they were offered, by place. */
+    options: z.array(flowChoiceOptionSchema),
+    /** Whether a reply is taken instead (the zone has somewhere replies go). */
+    reply: z.boolean(),
+});
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/** A kept item as 0.9.36 read it: its five words (a web link), and a screenshot id only when it is a whole number. */
+const savedItemSchema = z.object({ ...flowSendItemSchema.shape, shot: z.unknown() });
+export function readFlowItems(raw) {
+    if (!Array.isArray(raw))
+        return [];
+    return raw.flatMap(one => {
+        const read = savedItemSchema.safeParse(one);
+        if (!read.success)
+            return [];
+        const shot = read.data.shot;
+        return [{ ...read.data, shot: typeof shot === "number" && Number.isSafeInteger(shot) ? shot : null }];
+    });
+}
+/** Version 0: content kept before it carried `version`, in this contract's shape (what can't be read is left for the schema to refuse by path). */
+export function upgradeSavedSend(body) {
+    if (typeof body["title"] !== "string" || typeof body["summary"] !== "string" || !Array.isArray(body["links"]))
+        return body;
+    const items = readFlowItems(body["items"]);
+    const shots = sendShape.shots.safeParse(body["shots"]);
+    const out = {
+        version: FLOW_SEND_VERSION, title: body["title"], ...(typeof body["from"] === "string" ? { from: body["from"] } : {}), summary: body["summary"],
+        links: body["links"].filter(one => flowSendLinkSchema.safeParse(one).success), shots: shots.success ? shots.data : null,
+        ...(body["items"] === undefined || items.length === 0 ? {} : { items }),
+    };
+    if (Array.isArray(body["options"])) {
+        out["options"] = body["options"].filter(one => flowChoiceOptionSchema.safeParse(one).success);
+        out["reply"] = body["reply"] === true;
+    }
+    return out;
+}
+/** Read a visit's kept content: a choice's when it carries options, else a send's; version 0 upgraded, newer refused. */
+export function readFlowSendPayload(input) {
+    const choose = isRecord(input) && Object.prototype.hasOwnProperty.call(input, "options");
+    const read = choose ? readVersioned(flowChoosePayloadSchema, input, { 0: upgradeSavedSend }) : readVersioned(flowSendPayloadSchema, input, { 0: upgradeSavedSend });
+    if (!read.ok)
+        return read;
+    const { version: _version, ...content } = read.value;
+    return { ok: true, value: content };
+}
+/** A visit's content as it is kept: the payload of its kind, with the current version. */
+export function flowSendForStore(content) {
+    const payload = { version: FLOW_SEND_VERSION, ...content };
+    return JSON.stringify(content.options === undefined ? flowSendPayloadSchema.parse(payload) : flowChoosePayloadSchema.parse(payload));
+}
+// ------------------------------------------------------------------ the person's choice
+/** A person's answer to a choice: an option by its place (and the words and zone they saw), or a reply (`choice` null)
+ * that becomes the note for where replies go. `entry` is the visit they saw; without it, the card's current one. */
+export const flowChoiceAnswerSchema = z.strictObject({
+    card: z.int().min(1),
+    entry: z.int().min(1).optional(),
+    choice: z.int().min(0).nullable(),
+    label: z.string().optional(),
+    to: z.string().optional(),
+    note: z.string().nullable(),
+});
+export function readFlowChoiceAnswer(input) {
+    return parseContract(flowChoiceAnswerSchema, input);
+}

package/dist/contracts/flow.d.ts

@@ -85,6 +85,11 @@ export declare const flowSortNoteSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     question: z.ZodString;
     levels: z.ZodNull;
 }, z.core.$strict>], "kind">;
+/** How a sort answer is named to Jev: its words as a short key (the request's criteria, and the choice Jev returns). */
+export declare const sortKeyOf: (answer: string) => string;
+/** The key of a sort zone's question in its Jev request (a choice over its answers), and of each thing it also notes. */
+export declare const SORT_ROUTE_KEY = "route";
+export declare const sortNoteKeyOf: (noteId: string) => string;
 /** sort: the question, its answers, how sure Jev must be to act alone (0.5–0.99), and what else it notes. */
 export declare const flowSortSchema: z.ZodObject<{
     question: z.ZodString;

package/dist/contracts/flow.js

@@ -72,6 +72,11 @@ export const flowSortNoteSchema = z.discriminatedUnion("kind", [
     z.strictObject({ id: zoneId, kind: z.literal("score"), question: words("question", "flowSortQuestion").min(1), levels: z.array(words("level", "flowSortLevel").min(1)).min(SORT_LEVELS_MIN).max(SORT_LEVELS_MAX) }),
     z.strictObject({ id: zoneId, kind: z.literal("yes-no"), question: words("question", "flowSortQuestion").min(1), levels: z.null() }),
 ]);
+/** How a sort answer is named to Jev: its words as a short key (the request's criteria, and the choice Jev returns). */
+export const sortKeyOf = (answer) => answer.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 40) || "answer";
+/** The key of a sort zone's question in its Jev request (a choice over its answers), and of each thing it also notes. */
+export const SORT_ROUTE_KEY = "route";
+export const sortNoteKeyOf = (noteId) => `note_${noteId.replace(/-/g, "_")}`;
 /** sort: the question, its answers, how sure Jev must be to act alone (0.5–0.99), and what else it notes. */
 export const flowSortSchema = z.strictObject({
     question: words("question", "flowSortQuestion").min(1),