toolroll 0.9.34 → 0.9.37

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

@@ -0,0 +1,325 @@
+/**
+ * The lead's `propose_flow` input (docs/plans/zod-revamp.md, item 3): one schema, built from the flow contract's own
+ * step and trigger schemas, that is both the JSON Schema the lead is given and the check its call is read with
+ * (mate-tools.ts). The lead-tools contract (item 5) imports it from here rather than restating it.
+ */
+import { z } from "zod";
+export declare const PROPOSE_FLOW_OPERATIONS: readonly ["create", "edit", "add_card", "move_card", "approve", "send_back", "choose", "cancel_card", "comment", "assign", "follow", "unfollow", "save_script", "add_trigger", "pause_trigger", "resume_trigger", "remove_trigger", "kit", "starter"];
+export declare const proposeFlowInputSchema: z.ZodObject<{
+    operation: z.ZodEnum<{
+        add_card: "add_card";
+        add_trigger: "add_trigger";
+        approve: "approve";
+        assign: "assign";
+        cancel_card: "cancel_card";
+        choose: "choose";
+        comment: "comment";
+        create: "create";
+        edit: "edit";
+        follow: "follow";
+        kit: "kit";
+        move_card: "move_card";
+        pause_trigger: "pause_trigger";
+        remove_trigger: "remove_trigger";
+        resume_trigger: "resume_trigger";
+        save_script: "save_script";
+        send_back: "send_back";
+        starter: "starter";
+        unfollow: "unfollow";
+    }>;
+    repo: z.ZodOptional<z.ZodString>;
+    flow: z.ZodOptional<z.ZodInt>;
+    card: z.ZodOptional<z.ZodInt>;
+    kit: z.ZodOptional<z.ZodEnum<{
+        [x: string]: string;
+    }>>;
+    starter: z.ZodOptional<z.ZodEnum<{
+        "ci-fix": "ci-fix";
+        "issue-task": "issue-task";
+        overnight: "overnight";
+        "plane-review": "plane-review";
+    }>>;
+    name: z.ZodOptional<z.ZodString>;
+    template: z.ZodOptional<z.ZodEnum<{
+        [x: string]: string;
+    }>>;
+    steps: z.ZodOptional<z.ZodArray<z.ZodDiscriminatedUnion<readonly [z.ZodObject<{
+        id: z.ZodOptional<z.ZodString>;
+        title: z.ZodString;
+        kind: z.ZodLiteral<"inbox">;
+        ifFails: z.ZodOptional<z.ZodString>;
+        next: z.ZodOptional<z.ZodString>;
+        remindAfter: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodInt]>>;
+        thenMoveTo: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>, z.ZodObject<{
+        id: z.ZodOptional<z.ZodString>;
+        title: z.ZodString;
+        kind: z.ZodLiteral<"task">;
+        ifFails: z.ZodOptional<z.ZodString>;
+        instructions: z.ZodOptional<z.ZodString>;
+        next: z.ZodOptional<z.ZodString>;
+        planning: z.ZodOptional<z.ZodEnum<{
+            auto: "auto";
+            required: "required";
+            skip: "skip";
+        }>>;
+        remindAfter: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodInt]>>;
+        repo: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>, z.ZodObject<{
+        id: z.ZodOptional<z.ZodString>;
+        title: z.ZodString;
+        kind: z.ZodLiteral<"report">;
+        ifFails: z.ZodOptional<z.ZodString>;
+        instructions: z.ZodOptional<z.ZodString>;
+        next: z.ZodOptional<z.ZodString>;
+        remindAfter: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodInt]>>;
+    }, z.core.$strict>, z.ZodObject<{
+        id: z.ZodOptional<z.ZodString>;
+        title: z.ZodString;
+        kind: z.ZodLiteral<"approval">;
+        decider: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        ifFails: z.ZodOptional<z.ZodString>;
+        next: z.ZodOptional<z.ZodString>;
+        remindAfter: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodInt]>>;
+        teammate: z.ZodOptional<z.ZodString>;
+        thenMoveTo: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>, z.ZodObject<{
+        id: z.ZodOptional<z.ZodString>;
+        title: z.ZodString;
+        kind: z.ZodLiteral<"check">;
+        ifFails: z.ZodOptional<z.ZodString>;
+        next: z.ZodOptional<z.ZodString>;
+        remindAfter: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodInt]>>;
+        routes: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            answer: z.ZodString;
+            goesTo: z.ZodString;
+        }, z.core.$strict>>>;
+        runIn: z.ZodOptional<z.ZodEnum<{
+            copy: "copy";
+            folder: "folder";
+        }>>;
+        script: z.ZodOptional<z.ZodString>;
+        secrets: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>, z.ZodObject<{
+        id: z.ZodOptional<z.ZodString>;
+        title: z.ZodString;
+        kind: z.ZodLiteral<"pull-request">;
+        ifFails: z.ZodOptional<z.ZodString>;
+        merge: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodEnum<{
+            merge: "merge";
+            rebase: "rebase";
+            squash: "squash";
+        }>]>>;
+        next: z.ZodOptional<z.ZodString>;
+        remindAfter: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodInt]>>;
+    }, z.core.$strict>, z.ZodObject<{
+        id: z.ZodOptional<z.ZodString>;
+        title: z.ZodString;
+        kind: z.ZodLiteral<"update">;
+        close: z.ZodOptional<z.ZodBoolean>;
+        ifFails: z.ZodOptional<z.ZodString>;
+        message: z.ZodOptional<z.ZodString>;
+        next: z.ZodOptional<z.ZodString>;
+        remindAfter: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodInt]>>;
+    }, z.core.$strict>, z.ZodObject<{
+        id: z.ZodOptional<z.ZodString>;
+        title: z.ZodString;
+        kind: z.ZodLiteral<"notify">;
+        ifFails: z.ZodOptional<z.ZodString>;
+        message: z.ZodOptional<z.ZodString>;
+        next: z.ZodOptional<z.ZodString>;
+        remindAfter: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodInt]>>;
+    }, z.core.$strict>, z.ZodObject<{
+        id: z.ZodOptional<z.ZodString>;
+        title: z.ZodString;
+        kind: z.ZodLiteral<"sort">;
+        alsoNote: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            id: z.ZodOptional<z.ZodString>;
+            question: z.ZodString;
+            kind: z.ZodOptional<z.ZodEnum<{
+                score: "score";
+                "yes-no": "yes-no";
+            }>>;
+            levels: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$strict>>>;
+        answers: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            answer: z.ZodString;
+            means: z.ZodOptional<z.ZodString>;
+            goesTo: z.ZodString;
+        }, z.core.$strict>>>;
+        ifNotSure: z.ZodOptional<z.ZodString>;
+        question: z.ZodOptional<z.ZodString>;
+        remindAfter: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodInt]>>;
+        sureAt: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>, z.ZodObject<{
+        id: z.ZodOptional<z.ZodString>;
+        title: z.ZodString;
+        kind: z.ZodLiteral<"draft">;
+        ifFails: z.ZodOptional<z.ZodString>;
+        instructions: z.ZodOptional<z.ZodString>;
+        next: z.ZodOptional<z.ZodString>;
+        remindAfter: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodInt]>>;
+    }, z.core.$strict>, z.ZodObject<{
+        id: z.ZodOptional<z.ZodString>;
+        title: z.ZodString;
+        kind: z.ZodLiteral<"request">;
+        body: z.ZodOptional<z.ZodString>;
+        headers: z.ZodOptional<z.ZodObject<{}, z.core.$catchall<z.ZodString>>>;
+        ifFails: z.ZodOptional<z.ZodString>;
+        method: z.ZodOptional<z.ZodEnum<{
+            DELETE: "DELETE";
+            GET: "GET";
+            PATCH: "PATCH";
+            POST: "POST";
+            PUT: "PUT";
+        }>>;
+        next: z.ZodOptional<z.ZodString>;
+        remindAfter: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodInt]>>;
+        url: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>, z.ZodObject<{
+        id: z.ZodOptional<z.ZodString>;
+        title: z.ZodString;
+        kind: z.ZodLiteral<"email">;
+        body: z.ZodOptional<z.ZodString>;
+        ifFails: z.ZodOptional<z.ZodString>;
+        next: z.ZodOptional<z.ZodString>;
+        remindAfter: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodInt]>>;
+        subject: z.ZodOptional<z.ZodString>;
+        to: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>, z.ZodObject<{
+        id: z.ZodOptional<z.ZodString>;
+        title: z.ZodString;
+        kind: z.ZodLiteral<"tool">;
+        args: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{}, z.core.$catchall<z.ZodUnknown>>, z.ZodString]>>;
+        ifFails: z.ZodOptional<z.ZodString>;
+        next: z.ZodOptional<z.ZodString>;
+        remindAfter: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodInt]>>;
+        server: z.ZodOptional<z.ZodString>;
+        tool: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>, z.ZodObject<{
+        id: z.ZodOptional<z.ZodString>;
+        title: z.ZodString;
+        kind: z.ZodLiteral<"wait">;
+        from: z.ZodOptional<z.ZodString>;
+        ifNoReply: z.ZodOptional<z.ZodString>;
+        next: z.ZodOptional<z.ZodString>;
+        timeZone: z.ZodOptional<z.ZodString>;
+        until: z.ZodOptional<z.ZodString>;
+        wait: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodInt]>>;
+        waitFor: z.ZodOptional<z.ZodEnum<{
+            hours: "hours";
+            reply: "reply";
+            time: "time";
+        }>>;
+    }, z.core.$strict>, z.ZodObject<{
+        id: z.ZodOptional<z.ZodString>;
+        title: z.ZodString;
+        kind: z.ZodLiteral<"teammate">;
+        ifFails: z.ZodOptional<z.ZodString>;
+        instructions: z.ZodOptional<z.ZodString>;
+        next: z.ZodOptional<z.ZodString>;
+        remindAfter: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodInt]>>;
+        reply: z.ZodOptional<z.ZodBoolean>;
+        routes: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            answer: z.ZodString;
+            goesTo: z.ZodString;
+        }, z.core.$strict>>>;
+        teammate: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>, z.ZodObject<{
+        id: z.ZodOptional<z.ZodString>;
+        title: z.ZodString;
+        kind: z.ZodLiteral<"send">;
+        ifFails: z.ZodOptional<z.ZodString>;
+        next: z.ZodOptional<z.ZodString>;
+        remindAfter: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodInt]>>;
+    }, z.core.$strict>, z.ZodObject<{
+        id: z.ZodOptional<z.ZodString>;
+        title: z.ZodString;
+        kind: z.ZodLiteral<"choose">;
+        ifNoReply: z.ZodOptional<z.ZodString>;
+        ifReplied: z.ZodOptional<z.ZodString>;
+        options: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            label: z.ZodString;
+            goesTo: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>>;
+        remindAfter: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodInt]>>;
+        thenMoveTo: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>, z.ZodObject<{
+        id: z.ZodOptional<z.ZodString>;
+        title: z.ZodString;
+        kind: z.ZodLiteral<"done">;
+    }, z.core.$strict>], "kind">>>;
+    title: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    zone: z.ZodOptional<z.ZodString>;
+    note: z.ZodOptional<z.ZodString>;
+    choice: z.ZodOptional<z.ZodInt>;
+    trigger: z.ZodOptional<z.ZodInt>;
+    owner: z.ZodOptional<z.ZodString>;
+    script: z.ZodOptional<z.ZodObject<{
+        name: z.ZodOptional<z.ZodString>;
+        about: z.ZodOptional<z.ZodString>;
+        body: z.ZodOptional<z.ZodString>;
+        timeoutMinutes: z.ZodOptional<z.ZodInt>;
+        language: z.ZodOptional<z.ZodEnum<{
+            node: "node";
+            python: "python";
+            shell: "shell";
+        }>>;
+        file: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    settings: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        zone: z.ZodOptional<z.ZodString>;
+        kind: z.ZodLiteral<"button">;
+        label: z.ZodString;
+        questions: z.ZodOptional<z.ZodUnion<readonly [z.ZodArray<z.ZodString>, z.ZodString]>>;
+    }, z.core.$strict>, z.ZodObject<{
+        zone: z.ZodOptional<z.ZodString>;
+        kind: z.ZodLiteral<"schedule">;
+        schedule: z.ZodString;
+        title: z.ZodOptional<z.ZodString>;
+        description: z.ZodOptional<z.ZodString>;
+        script: z.ZodOptional<z.ZodString>;
+        secrets: z.ZodOptional<z.ZodUnion<readonly [z.ZodArray<z.ZodString>, z.ZodString]>>;
+    }, z.core.$strict>, z.ZodObject<{
+        zone: z.ZodOptional<z.ZodString>;
+        kind: z.ZodLiteral<"github">;
+        repo: z.ZodOptional<z.ZodString>;
+        watch: z.ZodOptional<z.ZodEnum<{
+            checks: "checks";
+            issues: "issues";
+            pulls: "pulls";
+        }>>;
+        label: z.ZodOptional<z.ZodString>;
+        branch: z.ZodOptional<z.ZodString>;
+        from: z.ZodOptional<z.ZodEnum<{
+            anyone: "anyone";
+            team: "team";
+        }>>;
+    }, z.core.$strict>, z.ZodObject<{
+        zone: z.ZodOptional<z.ZodString>;
+        kind: z.ZodLiteral<"linear">;
+        team: z.ZodOptional<z.ZodString>;
+        state: z.ZodOptional<z.ZodString>;
+        label: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>, z.ZodObject<{
+        zone: z.ZodOptional<z.ZodString>;
+        kind: z.ZodLiteral<"flow">;
+        when: z.ZodOptional<z.ZodString>;
+        follow: z.ZodInt;
+    }, z.core.$strict>, z.ZodObject<{
+        zone: z.ZodOptional<z.ZodString>;
+        kind: z.ZodLiteral<"email">;
+        folder: z.ZodOptional<z.ZodString>;
+        sender: z.ZodOptional<z.ZodString>;
+        subject: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>, z.ZodObject<{
+        zone: z.ZodOptional<z.ZodString>;
+        kind: z.ZodLiteral<"plane-review">;
+        at: z.ZodOptional<z.ZodString>;
+        timeZone: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>], "kind">>;
+}, z.core.$strict>;
+export type ProposeFlowInput = z.infer<typeof proposeFlowInputSchema>;
+/** What the lead is told propose_flow takes: exactly the schema its call is read with. */
+export declare const PROPOSE_FLOW_MODEL_SCHEMA: Readonly<Record<string, unknown>>;

package/dist/contracts/flow-propose.js

@@ -0,0 +1,41 @@
+/**
+ * The lead's `propose_flow` input (docs/plans/zod-revamp.md, item 3): one schema, built from the flow contract's own
+ * step and trigger schemas, that is both the JSON Schema the lead is given and the check its call is read with
+ * (mate-tools.ts). The lead-tools contract (item 5) imports it from here rather than restating it.
+ */
+import { z } from "zod";
+import { LIMITS } from "../decision.js";
+import { STARTER_IDS } from "../flow-starters.js";
+import { FLOW_TEMPLATES } from "../flows.js";
+import { KITS } from "../kits.js";
+import { TEXT_LIMITS } from "../text-limits.js";
+import { toModelSchema } from "./contract.js";
+import { flowStepsSchema, leadTriggerSchema, SCRIPT_LANGUAGES, SCRIPT_NAME } from "./flow.js";
+export const PROPOSE_FLOW_OPERATIONS = ["create", "edit", "add_card", "move_card", "approve", "send_back", "choose", "cancel_card", "comment", "assign", "follow", "unfollow", "save_script", "add_trigger", "pause_trigger", "resume_trigger", "remove_trigger", "kit", "starter"];
+const id = z.int().min(1);
+const enumOf = (values) => z.enum(values);
+export const proposeFlowInputSchema = z.strictObject({
+    operation: z.enum(PROPOSE_FLOW_OPERATIONS),
+    /** A project as list_repos names it (r1, r2). */
+    repo: z.string().regex(/^r[0-9]{1,3}$/, { error: "must be a project from list_repos, like r1" }).optional(),
+    flow: id.optional(), card: id.optional(),
+    kit: enumOf(KITS.map(one => one.id)).optional(),
+    starter: z.enum(STARTER_IDS).optional(),
+    name: z.string().max(TEXT_LIMITS.flowName).optional(),
+    template: enumOf(FLOW_TEMPLATES.map(one => one.id)).optional(),
+    steps: flowStepsSchema.shape.steps.optional(),
+    title: z.string().max(TEXT_LIMITS.flowCardTitle).optional(),
+    description: z.string().max(TEXT_LIMITS.flowCardDescription).optional(),
+    zone: z.string().max(TEXT_LIMITS.flowRef).optional(),
+    note: z.string().max(LIMITS.note).describe(`At most ${LIMITS.note} characters; longer is refused with its length, not cut.`).optional(),
+    choice: z.int().min(1).max(4).optional(),
+    trigger: id.optional(),
+    owner: z.string().max(TEXT_LIMITS.flowDecider).optional(),
+    script: z.strictObject({
+        name: z.string().regex(SCRIPT_NAME, { error: "must be a script's name: lowercase letters, numbers and dashes" }).optional(), about: z.string().max(TEXT_LIMITS.flowScriptAbout).optional(), body: z.string().max(TEXT_LIMITS.flowScriptInline).optional(),
+        timeoutMinutes: z.int().min(1).max(60).optional(), language: z.enum(SCRIPT_LANGUAGES).optional(), file: z.string().max(TEXT_LIMITS.flowScriptFile).optional(),
+    }).optional(),
+    settings: leadTriggerSchema.optional(),
+});
+/** What the lead is told propose_flow takes: exactly the schema its call is read with. */
+export const PROPOSE_FLOW_MODEL_SCHEMA = toModelSchema(proposeFlowInputSchema);

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);
+}