toolroll 0.9.34 → 0.9.37

package/dist/flows.d.ts

@@ -1,172 +1,55 @@
-export declare const FLOW_STAGE_KINDS: readonly ["inbox", "task", "report", "approval", "check", "pull-request", "update", "notify", "sort", "draft", "request", "email", "tool", "wait", "teammate", "send", "choose", "done"];
-export type FlowStageKind = (typeof FLOW_STAGE_KINDS)[number];
-export declare const FLOW_COLORS: readonly ["slate", "blue", "violet", "amber", "green", "rose"];
-export type FlowColor = (typeof FLOW_COLORS)[number];
-export type FlowZone = {
-    x: number;
-    y: number;
-    w: number;
-    h: number;
-    color: FlowColor;
-};
-/** One answer a sort zone can pick: its name, what it means (what Jev reads), and the zone it sends the card to. */
-export type FlowSortAnswer = {
-    answer: string;
-    means: string;
-    to: string;
-};
-/** Something else a sort zone notes on the card: a score on a scale of levels, or a yes/no. */
-export type FlowSortNote = {
-    id: string;
-    kind: "score" | "yes-no";
-    question: string;
-    levels: string[] | null;
-};
-/** sort: the question, its answers, how sure Jev must be to act alone (0.5–0.99), and what else it notes. */
-export type FlowSort = {
-    question: string;
-    answers: FlowSortAnswer[];
-    sureAt: number;
-    notes: FlowSortNote[];
-};
-/** request: what is called. The address's scheme and host are fixed; fill-ins go in its path and query (encoded), headers and body. */
-export type FlowRequest = {
-    method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
-    url: string;
-    headers: Record<string, string>;
-    body: string | null;
-};
-/** email: who it goes to, the subject and the text — all with fill-ins. */
-export type FlowEmail = {
-    to: string;
-    subject: string;
-    body: string;
-};
-/** tool: which of the project's tools (MCP servers), which of its functions, and the arguments as JSON with fill-ins. */
-export type FlowTool = {
-    server: string;
-    name: string;
-    args: string;
-};
-/** wait (v91): for a reply to the card's email (next: replied, onFail: no reply in time), or for a set time (then next).
- * "hours": until the clock is between `from` and `to` (like 22:00–06:00), in the computer's time zone unless one is named. */
-export type FlowWait = {
-    for: "reply" | "time" | "hours";
-    minutes: number;
-    from?: string;
-    to?: string;
-    timeZone?: string;
-};
-/** How a Pull request zone merges once checks pass. */
-export declare const FLOW_MERGE_METHODS: readonly ["squash", "merge", "rebase"];
-export type FlowMergeMethod = (typeof FLOW_MERGE_METHODS)[number];
-/** A choose zone's option: its button's words, and the zone it leads to (FLOW_END closes the card as Ignored). */
-export type FlowChoice = {
-    label: string;
-    to: string;
-};
-/** Where a choose option that ends the card leads. */
-export declare const FLOW_END = "end";
-/** How many options a choose zone offers. */
-export declare const CHOICES_MIN = 2, CHOICES_MAX = 4;
-/** A time limit on a zone (v91): after this long, the person it waits on is reminded, and a Holding or
- * "Person decides" zone can move the card on (`to`). */
-export type FlowLimit = {
-    minutes: number;
-    to: string | null;
-};
-export type FlowStage = {
-    id: string;
-    title: string;
-    kind: FlowStageKind;
-    zone: FlowZone;
-    /** task/report: what the agent is asked to do. `{{card.title}}`,
-     * `{{card.description}}`, `{{note}}` (the latest send-back note) and
-     * `{{stage.<id>}}` (an earlier zone's report) are filled in. */
-    instructions: string | null;
-    /** task: plan first (required), let Toolroll decide (auto), or build directly (skip). */
-    planning: "auto" | "required" | "skip" | null;
-    /** approval: the one person who decides, or null for any approver on the project. */
-    approver: string | null;
-    /** approval: the flow's owner decides (v86), whoever that is when the card arrives; `approver` is then unused. */
-    toOwner?: boolean;
-    /** notify: the message; update: the comment left on the issue. Same fill-ins. */
-    message: string | null;
-    /** update: also close the issue (Linear: move it to the team's done state). */
-    close: boolean | null;
-    /** check: the project script (by name) run with no AI. */
-    script: string | null;
-    /** check (v90): where it runs — a clean folder, or a copy of the card's work (the default for zones made before v90);
-     * the answers a script's "goto:" line may pick, each with the zone it leads to; and the flow secrets it gets as variables. */
-    runIn?: "folder" | "copy";
-    routes?: {
-        answer: string;
-        to: string;
-    }[];
-    secrets?: string[];
-    /** sort: what Jev is asked and where each answer leads. Its onFail is where a card goes when Jev isn't sure. */
-    sort: FlowSort | null;
-    /** request, email, tool (v87): what the step sends, and to where. */
-    request?: FlowRequest;
-    email?: FlowEmail;
-    tool?: FlowTool;
-    /** wait (v91): what it waits for, and how long. */
-    wait?: FlowWait;
-    /** Any zone but Wait and Done (v91): how long a card may sit here before someone is reminded. */
-    limit?: FlowLimit;
-    /** v92: the AI teammate (by handle) who decides a "Person decides" zone (handing hard ones to its person), or handles a "Teammate handles it" zone. */
-    teammate?: string;
-    /** v96: a "Teammate handles it" zone sends what the teammate writes back to whoever asked (the person who added the card, its chat thread, or the teammate's manager). */
-    reply?: boolean;
-    /** choose: the buttons the person picks from, in order. Its onFail is where a reply goes, with the reply as {{note}}. */
-    options?: FlowChoice[];
-    /** task: the project it builds in, when not the flow's own (one the flow's owner may file in). */
-    repo?: string;
-    /** pull-request: merge once checks pass, this way. Only allowed after a "Person decides" zone, and a card merges only when a person approved it after it was built. */
-    merge?: FlowMergeMethod;
-    /** Where a card goes when this zone's step succeeds, and when it fails or is sent back (sort: when it isn't sure). */
-    next: string | null;
-    onFail: string | null;
-};
-export type FlowDefinition = {
-    version: 1;
-    start: string;
-    stages: FlowStage[];
-};
+import { type ContractIssue, type ContractResult } from "./contracts/contract.js";
+import { CHOICES_MAX, CHOICES_MIN, FLOW_COLORS, FLOW_END, FLOW_MERGE_METHODS, FLOW_STAGE_KINDS, LONGEST_WAIT_MINUTES, SCRIPT_LANGUAGES, SCRIPT_NAME, sortKeyOf, type FlowDefinition, type FlowStage, type FlowStageKind, type FlowStepFields, type FlowWait, type ScriptLanguage, type TriggerInput } from "./contracts/flow.js";
+export { CHOICES_MAX, CHOICES_MIN, FLOW_COLORS, FLOW_END, FLOW_MERGE_METHODS, FLOW_STAGE_KINDS, LONGEST_WAIT_MINUTES, SCRIPT_LANGUAGES, SCRIPT_NAME, sortKeyOf };
+export type { FlowChoice, FlowColor, FlowDefinition, FlowEmail, FlowLimit, FlowMergeMethod, FlowRequest, FlowSort, FlowSortAnswer, FlowSortNote, FlowStage, FlowStageKind, FlowStepInput, FlowTool, FlowWait, FlowZone, ScriptLanguage, } from "./contracts/flow.js";
 /** What each kind is called and does, in the words the canvas uses. */
 export declare const FLOW_KIND_WORDS: Record<FlowStageKind, {
     label: string;
     about: string;
 }>;
-/** A project script's name: short, lowercase, dashes — how zones and chat refer to it. */
-export declare const SCRIPT_NAME: RegExp;
-/** The languages a project script is written in (v90). */
-export declare const SCRIPT_LANGUAGES: readonly ["shell", "python", "node"];
-export type ScriptLanguage = (typeof SCRIPT_LANGUAGES)[number];
 export declare const LANGUAGE_WORDS: Record<ScriptLanguage, string>;
-/** How an answer is named to Jev: its words as a short key. */
-export declare const sortKeyOf: (answer: string) => string;
 /** The default for "sure enough to act alone". */
 export declare const SORT_SURE_AT = 0.8;
-/** The longest a zone waits or a limit runs: 30 days. */
-export declare const LONGEST_WAIT_MINUTES: number;
 /** "3 days", "4 hours", "90 minutes", "1 week" (or a number of minutes) as minutes; null when it isn't one. */
 export declare function durationMinutes(value: unknown): number | null;
 /** Minutes in the words people use: "3 days", "1 day 4 hours", "45 minutes". */
 export declare function durationWords(minutes: number): string;
 /** "22:00", "9:30" as "HH:MM"; null when it isn't a time of day. */
 export declare function clockTime(value: unknown): string | null;
+export declare function knownTimeZone(zone: string): boolean;
 /** Whether a time falls inside an "hours" wait (22:00–06:00 runs past midnight), in its time zone or this computer's. */
 export declare function withinHours(wait: Pick<FlowWait, "from" | "to" | "timeZone">, now: Date): boolean;
 /** Who decides at an approval zone: its named person, the flow's owner, or null for anyone who approves on the project. */
 export declare function deciderOf(stage: Pick<FlowStage, "approver" | "toOwner">, flow: {
     owner: string;
 }): string | null;
-/** A flow as drawn on the canvas, checked whole. Throws in plain words. */
-/** `stored`: reading a flow saved earlier, which keeps working under rules added since (its cards say what's wrong). */
+/** A flow refused by its contract: every problem, each naming its path (`stages[2].instructions: required`). */
+export declare class FlowContractError extends Error {
+    readonly lines: readonly string[];
+    constructor(lines: readonly string[]);
+}
+/** What JSON Schema can't say about a drawing, each named by its path: paths lead to zones that exist and never back into
+ * their own zone, answers and options have names of their own, a web address's host is written out, tool arguments are a
+ * JSON object, an hours wait's times differ in a real time zone, and a merge comes after a person's decision. */
+export declare function drawingProblems(definition: FlowDefinition): ContractIssue[];
+/**
+ * Read a flow's drawing: the canvas's, a step list's once built, or one saved earlier (`stored`, which keeps working under
+ * rules added since: its instructions keep the length they were saved with). A version 1 drawing is read as every release
+ * has read it (canonicalStage), then the schema checks it, then drawingProblems; a newer version is refused plainly.
+ */
+export declare function readFlowDefinition(input: unknown, options?: {
+    stored?: boolean;
+}): ContractResult<FlowDefinition>;
+/** A refusal of the drawing a step list or flow file became, in its words: `stages[2].sort.answers[0].to` is
+ * `steps[2].answers[0].goesTo` (each zone is the step at its index), and a zone's failure path is the step's own name for it. */
+export declare function inStepWords(line: string, list: "steps" | "zones", kinds: readonly (string | undefined)[]): string;
+/** A flow as drawn on the canvas, checked whole (readFlowDefinition). Throws FlowContractError, naming every path. */
 export declare function validateFlowDefinition(input: unknown, options?: {
     stored?: boolean;
 }): FlowDefinition;
+/** A drawing's refusal as the canvas shows it: each line as it is, after the name of the zone it is about, so a person
+ * finds it on the canvas (`Build · stages[1].instructions: required`). */
+export declare function withZoneNames(lines: readonly string[], input: unknown): string;
 /** The instructions 0.9.26 and earlier read from a saved zone: they re-check this length on every read, and a flow with a
  * longer one won't load. A saved zone keeps its first part under it, and the rest in `instructionsMore`, which they ignore. */
 export declare const FLOW_INSTRUCTIONS_STORED = 4000;
@@ -217,86 +100,21 @@ export declare function cardEmailOf(card: {
     title: string;
     description: string | null;
 }): string;
-/** A step as the lead describes it, in list order. A step that keeps an
- * existing zone (by `id`) carries over whatever it leaves out. */
-export type FlowStepInput = {
-    id?: string;
-    title?: string;
-    kind?: FlowStageKind;
-    instructions?: string;
-    planning?: "auto" | "required" | "skip";
-    decider?: string | null;
-    message?: string;
-    script?: string;
-    close?: boolean;
-    /** check (v90): "folder" (a clean folder) or "copy" (a copy of the card's work); the answers a "goto:" line picks, each with the step it goes to; saved secrets it gets. */
-    runIn?: "folder" | "copy";
-    routes?: {
-        answer?: string;
-        goesTo?: string;
-    }[];
-    secrets?: string[];
-    /** sort: the question, each answer with what it means and the step it goes to, how sure Jev must be (a percentage), and up to 3 other things to note. */
-    question?: string;
-    answers?: {
-        answer?: string;
-        means?: string;
-        goesTo?: string;
-    }[];
-    sureAt?: number;
-    alsoNote?: {
-        question?: string;
-        kind?: "score" | "yes-no";
-        levels?: string[];
-    }[];
-    /** request: method, address, headers and body; email: to, subject, body; tool: the tool (server), its function (tool) and arguments. */
-    method?: FlowRequest["method"];
-    url?: string;
-    headers?: Record<string, string>;
-    body?: string;
-    to?: string;
-    subject?: string;
-    server?: string;
-    tool?: string;
-    args?: Record<string, unknown> | string;
-    /** wait (v91): for a reply (the default) or a set time, and how long ("3 days"); where a card goes when no reply comes.
-     * "hours": until the clock is between `from` and `until` ("22:00", "06:00"). */
-    waitFor?: "reply" | "time" | "hours";
-    wait?: string | number;
-    ifNoReply?: string;
-    from?: string;
-    until?: string;
-    /** pull-request: merge once checks pass (true is squash). Needs a decision before it. */
-    merge?: boolean | FlowMergeMethod;
-    /** Any step but wait and done (v91): remind after this long ("2 days"; "none" removes it), and on holding and approval steps, move the card to this step then. */
-    remindAfter?: string | number;
-    thenMoveTo?: string;
-    /** v92: the AI teammate (by name) who decides an approval step (handing hard ones to its decider) or handles a teammate step. */
-    teammate?: string;
-    /** v96: a teammate step sends what it writes back to whoever asked. */
-    reply?: boolean;
-    /** choose: 2 to 4 buttons, each with its words and the step it goes to ("end" ignores the card); where a reply goes instead
-     * (the reply is its {{note}}; the nearest earlier build or research step when left out). ifNoReply (with remindAfter) moves it on. */
-    options?: {
-        label?: string;
-        goesTo?: string;
-    }[];
-    ifReplied?: string;
-    /** task: the project it builds in (path), when not the flow's own. */
-    repo?: string;
-    next?: string;
-    ifFails?: string;
-    ifNotSure?: string;
-};
 /** What a draft zone asks for when the steps leave it out. */
 export declare const DRAFT_DEFAULT = "Write a short, friendly reply to the person who sent this card, in plain words.";
 /** Steps as the lead's flow tool and `toolroll flows` take them: "me" as a decider is the person asking, stored by name. */
 export declare function stepsFor(steps: unknown, name: string): unknown;
+/** An edit's steps with what a kept step leaves out of its kind and name filled from the zone it keeps (by id), so each
+ * reads as the one schema its kind has. Anything else it leaves out carries over when the flow is drawn (flowFromSteps). */
+export declare function withKeptSteps(steps: unknown, previous: FlowDefinition | null): unknown;
+/** A flow's steps, read by their one schema: `steps[0].routes[0]: unknown key 'to' (did you mean goesTo?)`. */
+export declare function readFlowSteps(input: unknown, previous?: FlowDefinition | null): ContractResult<FlowStepFields[]>;
 /**
  * A flow from an ordered list of steps: ids from names, each step leading
  * to the next, a Done zone at the end when none is listed, and a decision
  * sending work back to the nearest earlier step that does work. New zones
- * are laid out in rows; zones kept from `previous` keep their place.
+ * are laid out in rows; zones kept from `previous` keep their place. Throws
+ * FlowContractError, each line naming the step's path (`steps[2].next: ...`).
  */
 export declare function flowFromSteps(input: unknown, previous?: FlowDefinition | null): FlowDefinition;
 /** What confirming a new or changed flow means, in the canvas's words: each step's job and path, what changed, and that the usual approvals still apply. */
@@ -310,6 +128,5 @@ export declare const FLOW_TEMPLATES: readonly {
     label: string;
     about: string;
     definition: FlowDefinition;
-    trigger?: Record<string, unknown>;
+    trigger?: TriggerInput;
 }[];
-export {};