@engenty/wizards-runtime 0.0.0-stage → 0.7.5

package/node_modules/@engenty-wizards/shared/dist/space-data.js

@@ -0,0 +1,47 @@
+import { coerceColumnValue, TableColumnValueError, } from "./engenty/data-tables/index.js";
+export const SPACE_DATA_LIMITS = {
+    tables: 200,
+    /** Sub-pages count: a law split along its paragraphs is a few thousand. */
+    pages: 5000,
+    rowsPerTable: 5000,
+    pageChars: 200_000,
+};
+/**
+ * Cells a person typed, as stored: each value checked against its column. A blank cell is kept
+ * empty even where the column is required, so a row can be filled one cell at a time; cells of
+ * columns that no longer exist are dropped.
+ */
+export function editCells(columns, current, patch) {
+    const byId = new Map(columns.map((c) => [c.id, c]));
+    const next = {};
+    for (const [id, value] of Object.entries(current)) {
+        if (byId.has(id)) {
+            next[id] = value;
+        }
+    }
+    for (const [id, value] of Object.entries(patch)) {
+        const column = byId.get(id);
+        if (!column) {
+            throw new TableColumnValueError(id, `unknown column "${id}"`);
+        }
+        next[id] = coerceColumnValue({ ...column, required: false }, value);
+    }
+    return next;
+}
+/** A column id from its name: a lowercase slug, not one of `taken`. */
+export function columnIdOf(name, taken) {
+    const base = name
+        .normalize("NFKD")
+        .replace(/[̀-ͯ]/g, "")
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "_")
+        .replace(/^_+|_+$/g, "")
+        .replace(/^[^a-z]+/, "")
+        .slice(0, 48) || "column";
+    let id = base;
+    let i = 2;
+    while (taken.includes(id)) {
+        id = `${base}_${i++}`;
+    }
+    return id;
+}

package/node_modules/@engenty-wizards/shared/dist/store.d.ts

@@ -0,0 +1,117 @@
+import { type TableColumn } from "./engenty/data-tables/index.js";
+/**
+ * What a wizard keeps between runs for one person: lists (tabular data), files and connected
+ * accounts. The wizard definition says which lists and connections exist; the content belongs
+ * to the person who ran it.
+ */
+/** A list is an engenty data table: typed columns, rows of cells keyed by column id. */
+export interface ListDef {
+    id: string;
+    title: string;
+    description?: string;
+    columns: TableColumn[];
+    /** Column whose value identifies a row: saving a row with a known key updates it. */
+    key?: string;
+    /**
+     * The rows are gone through one by one in a review: `file` holds the path of a kept file
+     * shown beside the row, `status` is a select whose options are the answers (first = open).
+     */
+    check?: {
+        file?: string;
+        status?: string;
+    };
+    /** Every run reads and writes the same rows; kept as a table of the space, not per person. */
+    shared?: boolean;
+}
+export interface ListRow {
+    id: string;
+    cells: Record<string, unknown>;
+    updatedAt: string;
+}
+export interface StoreFile {
+    path: string;
+    mime: string;
+    size: number;
+    /** Where the file came from, in words: "E-Mail von billing@notion.so, 3.9.2026". */
+    source: string | null;
+    updatedAt: string;
+}
+export declare const STORE_LIMITS: {
+    fileBytes: number;
+    totalBytes: number;
+    files: number;
+    rowsPerList: number;
+};
+/** Kinds of accounts a wizard can ask the person to connect. */
+export declare const CONNECTION_KINDS: readonly ["mail"];
+export type ConnectionKind = (typeof CONNECTION_KINDS)[number];
+/** An account the person connects: a built-in kind, or one of the project's imported connectors. */
+export interface ConnectionDef {
+    id: string;
+    kind?: ConnectionKind;
+    /** Id of an imported connector of the project. */
+    connector?: string;
+    /** Imported connectors: the actions steps may call. Default: every action that only reads. */
+    actions?: string[];
+    /**
+     * Imported connectors: per action, run it without asking ("allow") or ask the person first
+     * ("ask"). Default: reading is allowed, changing asks; deleting always asks.
+     */
+    policy?: Record<string, "allow" | "ask">;
+    title?: string;
+    description?: string;
+}
+/** A connector the person can pick for a connection: an OAuth sign-in or a credentials form. */
+export interface ConnectorOption {
+    id: string;
+    name: string;
+    auth: "oauth2" | "api_key";
+    /** `api_key` connectors: the form, in order. */
+    fields?: {
+        key: string;
+        label: string;
+        secret?: boolean;
+        placeholder?: string;
+        required?: boolean;
+    }[];
+    /** Shown under the form: where to get the values. */
+    hint?: string;
+}
+export interface ConnectionView {
+    id: string;
+    kind: ConnectionKind | null;
+    /** The imported connector behind the connection, if it is one. */
+    connector: string | null;
+    title: string | null;
+    description: string | null;
+    /** Set when the person has connected an account. */
+    account: {
+        connector: string;
+        label: string;
+        connectedAt: string;
+    } | null;
+    connectors: ConnectorOption[];
+}
+/** One list as a Markdown table of raw cell values — what a model reads. */
+export declare function listAsMarkdown(def: ListDef, rows: ListRow[], limit?: number): string;
+/**
+ * When the first row saved now is stamped, in milliseconds: after every row the list already
+ * holds, so a list reads in the order its rows came — also when two saves fall in one
+ * millisecond. The rows of one save follow it a millisecond apart.
+ */
+export declare function firstRowAt(existing: {
+    createdAt: Date;
+}[]): number;
+/** The key a row is matched on: trimmed and lower-cased, so "Notion " and "notion" are one row. */
+export declare function rowKey(def: ListDef, cells: Record<string, unknown>): string | null;
+/** A new row's cells, typed by the list's columns. Throws `TableColumnValueError` on a bad value. */
+export declare function newCells(def: ListDef, input: Record<string, unknown>): Record<string, unknown>;
+/** An existing row's cells with some columns changed; cells of columns the list no longer has are dropped. */
+export declare function patchCells(def: ListDef, current: Record<string, unknown>, patch: Record<string, unknown>): Record<string, unknown>;
+/**
+ * What a person typed into a cell, as the value sent for its column; the runtime still checks it
+ * against the column. Blank is null; a number or a duration (in the column's input unit) is read
+ * as people write it ("12,5"); a date and time from the browser's picker, in local time, becomes
+ * ISO. What cannot be read goes as typed, for the runtime to refuse and name.
+ */
+export declare function cellValue(column: TableColumn, text: string): unknown;

package/node_modules/@engenty-wizards/shared/dist/store.js

@@ -0,0 +1,81 @@
+// SPDX-License-Identifier: FSL-1.1-MIT OR MIT
+import { coerceRowValues, mergeRowValues } from "./engenty/data-tables/index.js";
+import { readNumber } from "./numbers.js";
+export const STORE_LIMITS = {
+    fileBytes: 15_000_000,
+    totalBytes: 200_000_000,
+    files: 2000,
+    rowsPerList: 5000,
+};
+/** Kinds of accounts a wizard can ask the person to connect. */
+export const CONNECTION_KINDS = ["mail"];
+/** One list as a Markdown table of raw cell values — what a model reads. */
+export function listAsMarkdown(def, rows, limit = 200) {
+    if (!rows.length) {
+        return "(empty)";
+    }
+    const cols = def.columns;
+    const cell = (v) => v === null || v === undefined
+        ? ""
+        : (Array.isArray(v) ? v.join(", ") : String(v)).replace(/\|/g, "\\|").replace(/\s+/g, " ");
+    const head = `| ${cols.map((c) => c.id).join(" | ")} |\n|${cols.map(() => " --- ").join("|")}|`;
+    const body = rows
+        .slice(0, limit)
+        .map((r) => `| ${cols.map((c) => cell(r.cells[c.id])).join(" | ")} |`);
+    const more = rows.length > limit ? [`… ${rows.length - limit} more rows`] : [];
+    return [head, ...body, ...more].join("\n");
+}
+/**
+ * When the first row saved now is stamped, in milliseconds: after every row the list already
+ * holds, so a list reads in the order its rows came — also when two saves fall in one
+ * millisecond. The rows of one save follow it a millisecond apart.
+ */
+export function firstRowAt(existing) {
+    return existing.reduce((at, row) => Math.max(at, row.createdAt.getTime() + 1), Date.now());
+}
+/** The key a row is matched on: trimmed and lower-cased, so "Notion " and "notion" are one row. */
+export function rowKey(def, cells) {
+    if (!def.key) {
+        return null;
+    }
+    const raw = cells[def.key];
+    const key = raw === null || raw === undefined ? "" : String(raw).trim().toLowerCase();
+    return key || null;
+}
+/** A new row's cells, typed by the list's columns. Throws `TableColumnValueError` on a bad value. */
+export function newCells(def, input) {
+    return coerceRowValues(def.columns, input);
+}
+/** An existing row's cells with some columns changed; cells of columns the list no longer has are dropped. */
+export function patchCells(def, current, patch) {
+    const known = new Set(def.columns.map((c) => c.id));
+    const kept = Object.fromEntries(Object.entries(current).filter(([id]) => known.has(id)));
+    return mergeRowValues(def.columns, kept, patch);
+}
+/**
+ * What a person typed into a cell, as the value sent for its column; the runtime still checks it
+ * against the column. Blank is null; a number or a duration (in the column's input unit) is read
+ * as people write it ("12,5"); a date and time from the browser's picker, in local time, becomes
+ * ISO. What cannot be read goes as typed, for the runtime to refuse and name.
+ */
+export function cellValue(column, text) {
+    if (text.trim() === "") {
+        return null;
+    }
+    switch (column.type) {
+        case "number":
+        case "duration":
+            return readNumber(text) ?? text;
+        case "boolean":
+            return text === "true";
+        case "date": {
+            if (column.format.kind !== "datetime") {
+                return text;
+            }
+            const at = new Date(text);
+            return Number.isNaN(at.getTime()) ? text : at.toISOString();
+        }
+        default:
+            return text;
+    }
+}

package/node_modules/@engenty-wizards/shared/dist/surface.d.ts

@@ -0,0 +1,115 @@
+import { z } from "zod";
+import { type ObjectShape } from "./shape.js";
+/**
+ * Surfaces: views composed from a small catalog of native components, bound to a run's data and
+ * rendered by the runner itself — themed, on phones, no iframe and nothing to pay per run. A
+ * surface is data, not code: only catalog components render, so it needs no sandbox. Between the
+ * plain table a review shows and a widget, which is free HTML. As engenty-pro's A2UI catalog
+ * (`engenty:core/v1`), kept to what a wizard's result needs.
+ *
+ * A surface is a flat list of components with ids; the one with id "root" is drawn, containers
+ * name their children by id. A prop may be a literal or `{ "path": "/json/pointer" }` into the
+ * surface's data. A `List`, `Table` or `Group` repeats over an array: inside a repeated row, a
+ * path without a leading slash reads the row ("name"), one with a slash the whole data. A path
+ * may turn what it reads into words: `map` looks the value up (`{ "true": "im Kühlschrank" }`),
+ * `format` sets it into a text ("{} Min").
+ */
+export declare const SURFACE_COMPONENTS: readonly ["Column", "Text", "List", "Row", "DetailGrid", "Badge", "Grid", "Metric", "Table", "Image", "BarChart", "LineChart", "DonutChart", "Actions", "Button", "Tabs", "Card", "Fold", "Group", "Chips", "Checklist", "Steps", "Link", "Callout"];
+export type SurfaceComponentName = (typeof SURFACE_COMPONENTS)[number];
+export declare const SURFACE_ACTIONS: readonly ["regenerate", "open"];
+/** One component: its id, its kind, its children (ids, or a template repeated over an array). */
+export declare const surfaceComponentSchema: z.ZodObject<{
+    id: z.ZodString;
+    component: z.ZodEnum<{
+        Actions: "Actions";
+        Badge: "Badge";
+        BarChart: "BarChart";
+        Button: "Button";
+        Callout: "Callout";
+        Card: "Card";
+        Checklist: "Checklist";
+        Chips: "Chips";
+        Column: "Column";
+        DetailGrid: "DetailGrid";
+        DonutChart: "DonutChart";
+        Fold: "Fold";
+        Grid: "Grid";
+        Group: "Group";
+        Image: "Image";
+        LineChart: "LineChart";
+        Link: "Link";
+        List: "List";
+        Metric: "Metric";
+        Row: "Row";
+        Steps: "Steps";
+        Table: "Table";
+        Tabs: "Tabs";
+        Text: "Text";
+    }>;
+    children: z.ZodOptional<z.ZodUnion<readonly [z.ZodArray<z.ZodString>, z.ZodObject<{
+        path: z.ZodString;
+        componentId: z.ZodString;
+    }, z.core.$strip>]>>;
+}, z.core.$loose>;
+export type SurfaceComponent = z.infer<typeof surfaceComponentSchema>;
+export declare const surfaceComponentsSchema: z.ZodArray<z.ZodObject<{
+    id: z.ZodString;
+    component: z.ZodEnum<{
+        Actions: "Actions";
+        Badge: "Badge";
+        BarChart: "BarChart";
+        Button: "Button";
+        Callout: "Callout";
+        Card: "Card";
+        Checklist: "Checklist";
+        Chips: "Chips";
+        Column: "Column";
+        DetailGrid: "DetailGrid";
+        DonutChart: "DonutChart";
+        Fold: "Fold";
+        Grid: "Grid";
+        Group: "Group";
+        Image: "Image";
+        LineChart: "LineChart";
+        Link: "Link";
+        List: "List";
+        Metric: "Metric";
+        Row: "Row";
+        Steps: "Steps";
+        Table: "Table";
+        Tabs: "Tabs";
+        Text: "Text";
+    }>;
+    children: z.ZodOptional<z.ZodUnion<readonly [z.ZodArray<z.ZodString>, z.ZodObject<{
+        path: z.ZodString;
+        componentId: z.ZodString;
+    }, z.core.$strip>]>>;
+}, z.core.$loose>>;
+/** What a run shows: the components and the data they are bound to. */
+export interface Surface {
+    components: SurfaceComponent[];
+    data: Record<string, unknown>;
+}
+export interface SurfaceIssue {
+    message: string;
+}
+/**
+ * What can be wrong with a surface: an unknown or missing component, no root, a child that is
+ * not there, an id twice, a loop, a prop missing, and — given the data keys a run will provide,
+ * or the step's schema — a path into data nothing provides.
+ */
+export declare function validateSurface(raw: unknown, data?: string[] | ObjectShape): SurfaceIssue[];
+/** A JSON pointer into data: "/suppliers/0/name". */
+export declare function pointer(data: unknown, path: string): unknown;
+/**
+ * A prop's value: a literal as it is, a path read from the data — or, without a leading slash,
+ * from the row a List or Table repeats over.
+ */
+export declare function bound(value: unknown, data: unknown, row?: unknown): unknown;
+/** A value turned into words as its path says: looked up in `map`, set into `format`. */
+export declare function worded(raw: unknown, spec: {
+    map?: unknown;
+    format?: unknown;
+}): unknown;
+/** What a model needs to compose a surface: the catalog, briefly. */
+export declare const SURFACE_GUIDE = "A surface is a flat JSON array of components; the one with id \"root\" is drawn. Containers list their children by id.\nComponents and props (a prop may be a literal or {\"path\": \"/key/...\"} into the data):\n- Column { children: [ids] } \u2014 vertical stack (use for root); Column and Grid may also repeat one component per entry: children {\"path\", \"componentId\"}\n- Text { text, variant?: \"h3\"|\"h4\"|\"lead\"|\"body\"|\"muted\" } \u2014 \"lead\": the one opening line in the wizard's voice\n- List { children: {\"path\": \"/rows\", \"componentId\": \"<a Row id>\"} } \u2014 one Row per array entry; inside, paths without \"/\" read the entry (\"name\")\n- Row { title, subtitle?, meta?, badge?, image? }\n- DetailGrid { rows: [{ label, value }] } \u2014 label/value facts\n- Badge { label, tone?: \"default\"|\"success\"|\"warning\"|\"accent\" }\n- Grid { children: [ids], columns?: 2|3|4, min?: rem } \u2014 tiles side by side; min: the narrowest a tile gets (14 for cards, so a phone shows one)\n- Metric { label, value, caption? } \u2014 a key figure\n- Table { rows: {\"path\": \"/rows\"}, columns?: [{ key, label }] }\n- Image { src: an asset id or {\"path\": ...}, alt? }\n- BarChart / LineChart { title?, points: [{ label, value }] or {\"path\": ...}, labelKey?, valueKey? }\n- DonutChart { title?, slices: [{ label, value }] or {\"path\": ...}, labelKey?, valueKey? }\n  (labelKey / valueKey: the columns of bound rows that hold the label and the number, e.g. \"name\", \"price\")\n- Actions { children: [Button ids] } / Button { label, action: \"regenerate\"|\"open\" }\n- Tabs { tabs: [{ label, count?, child: id }] } \u2014 two to four views of one result; count may bind a list (shows its length)\n- Card { title, eyebrow?, subtitle?, meta?: [values], image?, children?: [ids] } \u2014 one thing: a day, a recipe, an offer\n- Fold { title, open?, children: [ids] } \u2014 details that open on a tap\n- Group { children: {\"path\", \"componentId\"}, by: \"<key>\", order?: [values] } \u2014 entries under a heading per value of a key\n- Chips { items, labelKey?, flagKey?, flag? } \u2014 short things at a glance; flagKey marks some (\"bald\")\n- Checklist { items, labelKey?, detailKey?, noteKey?, noteFormat?, noteMap?, groupKey?, groupOrder?, share? } \u2014 things to get or do; ticks are kept; a yes/no note needs noteMap: {\"true\": \"da\", \"false\": \"einkaufen\"}\n- Steps { items, textKey?, minutesKey? } \u2014 ordered work, numbered, with times\n- Link { title, subtitle?, eyebrow?, meta?, look?: \"row\"|\"card\", items: {\"path\": \"/recipes\"}, key?: \"id\", value: {\"path\": \"recipe_id\"}, view: id } \u2014 opens the entry of items whose key is value in a sheet, drawn by view; title, subtitle and meta read that entry, eyebrow the row the Link sits in\n- Callout { text, title?, tone?: \"tip\"|\"note\"|\"warning\" }\nA path may put its value into words: {\"path\": \"in_fridge\", \"map\": {\"true\": \"da\", \"false\": \"einkaufen\"}}, {\"path\": \"minutes\", \"format\": \"{} Min\"}.\nDesign it like an app, not a report: lead with a headline, the key figure or the chips; one Card per thing, never a Table of things; ordered work is Steps, things to get are a Checklist, sets are grouped by their key. A Table only for figures people compare across columns.\nKeep it small: what the person needs to see first, then the details. Never invent numbers: bind them by path.";