@anchrd/colab-sdk 0.1.10 → 0.1.12

package/dist/dashboards/dashboards.js

@@ -1,520 +0,0 @@
-import { z } from "zod";
-import { idSchema } from "../ids/ids.js";
-import { NodeId } from "../nodes/nodes.js";
-import { IdempotencyKey, Rev } from "../primitives/primitives.js";
-import { TimeZone } from "../profile/profile.js";
-// Dashboards (#44, Nodes › Dashboard, Funktionen › Läufe, E46, E70): the schedule, the configuration
-// (metrics, sections, boxes) and the run, the inputs of `intelligence_dashboard_create`, `_get`,
-// `_update`, and the answer. The configuration is ONE schema for the UI's forms (#61) and for the
-// YAML an AI writes: the backend parses the YAML first and then runs this schema, so both ways meet
-// the same checks. Every rule of the check is its own function below, and every finding names the
-// box it is about by its path (`["sections", 1, "boxes", 0, "uses"]`).
-//
-// ⚠️ No rule here may generate code from strings (trap P081): `workerd` refuses `eval` and
-// `new Function`, and the vitest pool patches them, so a test would pass where the Worker fails.
-// The checks are plain functions over the parsed object.
-export const DashboardId = idSchema("node").describe("The dashboard's id, its node id `node_…`, as intelligence_node_list or intelligence_dashboard_create returned it.");
-// ---------------------------------------------------------------------------------------------
-// The schedule (Ausführung): the same for a dashboard and a process board (#43).
-export const rhythms = ["manual", "daily", "weekly", "monthly", "dates"];
-export const weekdays = [
-    "monday",
-    "tuesday",
-    "wednesday",
-    "thursday",
-    "friday",
-    "saturday",
-    "sunday",
-];
-// No seconds and no zone on the string: a run happens at eight, and the zone is the schedule's own.
-// `24:00` is refused rather than read as midnight, so one moment has one spelling (anchrd/intel
-// `contract/process.ts`, f4eccd16).
-const TimeOfDay = z
-    .string()
-    .regex(/^([01]\d|2[0-3]):[0-5]\d$/, "A time of day is HH:MM, from 00:00 to 23:59, like 08:00.");
-// A fixed moment on the wall clock of the schedule's zone, without seconds and without an offset.
-const LocalMoment = z
-    .string()
-    .regex(/^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])T([01]\d|2[0-3]):[0-5]\d$/, "A date is YYYY-MM-DDTHH:MM on the schedule's clock, like 2026-10-15T08:00.");
-// Which fields each rhythm takes; every other one is refused, so nothing lies stored that no rhythm
-// reads.
-const rhythmFields = {
-    manual: [],
-    daily: ["times"],
-    weekly: ["days", "times"],
-    monthly: ["dayOfMonth", "times"],
-    dates: ["dates"],
-};
-const scheduleFields = ["days", "dayOfMonth", "times", "dates"];
-// What happens when a run falls due while the last one is still open (E75, Funktionen › Läufe):
-// wait (the default) starts none until the last is completed, continue starts it anyway and the
-// open ones stay open.
-export const whileOpenModes = ["wait", "continue"];
-export const WhileOpen = z
-    .enum(whileOpenModes)
-    .describe("When the last run is still open: wait (the default) starts no new run until it is completed, and the process stands overdue in the Actions; continue starts the new run anyway, and the open ones stay open.");
-export const Schedule = z
-    .strictObject({
-    rhythm: z
-        .enum(rhythms)
-        .describe("How often a run falls due: manual (a person starts it), daily, weekly (on days), monthly (on dayOfMonth), or dates (fixed moments, each once)."),
-    days: z
-        .array(z.enum(weekdays))
-        .min(1)
-        .max(7)
-        .optional()
-        .describe("The weekdays of a weekly rhythm, like [monday, thursday]. Only with weekly."),
-    dayOfMonth: z
-        .array(z.int().min(1).max(31))
-        .min(1)
-        .max(31)
-        .optional()
-        .describe("The days of the month of a monthly rhythm, like [1, 15]. A month without that day is skipped, never moved to its last day. Only with monthly."),
-    times: z
-        .array(TimeOfDay)
-        .min(1)
-        .max(24)
-        .optional()
-        .describe("The times of day a daily, weekly or monthly run falls due, HH:MM in zone, like [08:00]."),
-    dates: z
-        .array(LocalMoment)
-        .min(1)
-        .max(200)
-        .optional()
-        .describe("The fixed moments of the rhythm dates, YYYY-MM-DDTHH:MM in zone, each falling due once. Only with dates."),
-    zone: TimeZone.optional().describe("The IANA time zone the times and dates are read in, like Europe/Berlin. Leaving it out takes the time zone of the creator of the dashboard or process board."),
-    whileOpen: WhileOpen.optional().describe("When the last run is still open: wait starts no new run until it is completed, continue starts it anyway and the open ones stay open. Leaving it out is wait."),
-})
-    .superRefine((schedule, ctx) => {
-    const wanted = rhythmFields[schedule.rhythm];
-    for (const field of scheduleFields) {
-        const present = schedule[field] !== undefined;
-        if (wanted.includes(field) && !present) {
-            ctx.addIssue({
-                code: "custom",
-                path: [field],
-                message: `A ${schedule.rhythm} rhythm needs ${field}${field === "times" ? ", like [08:00]" : ""}.`,
-            });
-        }
-        if (!wanted.includes(field) && present) {
-            ctx.addIssue({
-                code: "custom",
-                path: [field],
-                message: `${field} belongs to ${field === "times" ? "a daily, weekly or monthly" : `a ${Object.entries(rhythmFields).find(([, fields]) => fields.includes(field))?.[0]}`} rhythm, not to ${schedule.rhythm}; leave it out.`,
-            });
-        }
-    }
-});
-// ---------------------------------------------------------------------------------------------
-// The configuration: metrics, sections, boxes (Nodes › Dashboard).
-export const boxTypes = ["metric", "line", "bar", "area", "summary", "note"];
-export const chartTypes = ["line", "bar", "area"];
-// A key stays fixed when the title changes, so old runs and table columns keep their place. It
-// starts with a letter, so an object keeps the order it was written in (JavaScript puts keys that
-// look like numbers first).
-export const DashboardKey = z
-    .string()
-    .regex(/^[a-z][a-z0-9_]{0,63}$/, "A key is lowercase letters, digits and underscores, starting with a letter, like lead_fit.");
-// Who delivers a metric's value or a summary's text in every run (E78, Nodes › Dashboard, Zuständig
-// je Kennzahl): a person or a machine that reads the dashboard. Without one the run has nobody for
-// that entry. Spelled out here instead of importing `users`, whose module graph reaches far.
-const Assignee = idSchema("user").describe("Who delivers this in every run, `user_…`: a person or a machine that can read the dashboard (find them with intelligence_node_grant_list or intelligence_user_list). Only they write its value, report and recommendation. Leaving it out leaves the entry without anybody.");
-// A required text whose absence says what it is for (trap P026: the schema's own sentence is all
-// a model reads).
-function required(max, missing) {
-    return z
-        .string({
-        error: (issue) => (issue.input === undefined ? missing : "This is text."),
-    })
-        .trim()
-        .min(1, missing)
-        .max(max);
-}
-const Text = z.string().max(10_000);
-const DashboardMetric = z
-    .strictObject({
-    title: required(200, "A metric needs a title: the label of its box and its name in every chart.").describe("The metric's name as people read it: the label of its box and of chart legends."),
-    description: Text.optional().describe("What people see as the tooltip of the metric."),
-    instructions: required(10_000, "A metric needs instructions: what it is and where the AI finds it.").describe("What the metric is and where the AI finds it, in plain sentences: what the Operator reads before every run."),
-    source: Text.optional().describe("Where the number comes from in words, like Leads Pipeline or DWH. The exact source of each value is in the run."),
-    assignee: Assignee.optional(),
-})
-    .describe("A metric, defined once: each run gives it a value and becomes one column of the table.");
-const DashboardBox = z
-    .strictObject({
-    metric: DashboardKey.optional().describe("A box showing one metric, named by its key in metrics. Takes no other field; it is 1 wide."),
-    line: DashboardKey.optional().describe("A line chart and its own key. Takes title, description and shows; it is 2 wide."),
-    bar: DashboardKey.optional().describe("A bar chart and its own key. Takes title, description and shows; it is 2 wide."),
-    area: DashboardKey.optional().describe("An area chart and its own key. Takes title, description and shows; it is 2 wide."),
-    summary: DashboardKey.optional().describe("A text the Operator writes each run, and its own key. Takes title, description, instructions, uses and width."),
-    note: DashboardKey.optional().describe("A fixed text by a person, and its own key. Takes title, description (its Markdown) and width."),
-    title: z.string().trim().max(200).optional().describe("The label of a chart, summary or note."),
-    description: Text.optional().describe("The tooltip of a chart's or summary's label; a note's visible text in Markdown."),
-    instructions: Text.optional().describe("What the Operator writes in a summary each run. A summary needs it."),
-    width: z
-        .int({ error: "width is 1, 2 or 3." })
-        .min(1, "width is 1, 2 or 3.")
-        .max(3, "width is 1, 2 or 3.")
-        .optional()
-        .describe("How many of the three columns a summary or note spans: 1, 2 or 3. Every other box has a fixed width."),
-    shows: z
-        .array(DashboardKey)
-        .max(20)
-        .optional()
-        .describe("The metrics a chart shows, by key, at least one, in the order of the legend."),
-    uses: z
-        .array(DashboardKey)
-        .max(50)
-        .optional()
-        .describe("The boxes of the same section a summary builds on, by key: a metric box by its metric's key."),
-    assignee: Assignee.optional().describe("Who writes a summary in every run, `user_…`: a person or a machine that can read the dashboard. Only on a summary. Leaving it out leaves the summary without anybody."),
-})
-    .describe("A box, written as its type and key (`metric: leads`, `line: trend`, `summary: verdict`, `note: hint`), then its fields.");
-const DashboardSection = z
-    .strictObject({
-    title: required(200, "A section needs a title: its heading.").describe("The section's heading."),
-    description: Text.optional().describe("The introduction under the heading, visible."),
-    boxes: z
-        .array(DashboardBox)
-        .max(60)
-        .default([])
-        .describe("The section's boxes in reading order: left to right, then the next row once the widths pass 3."),
-})
-    .describe("A section of the dashboard: a heading, an introduction and its boxes, 3 wide.");
-function placed(config) {
-    return config.sections.flatMap((section, s) => section.boxes.map((box, index) => ({
-        box,
-        section: s,
-        index,
-        types: boxTypes.filter((type) => box[type] !== undefined),
-    })));
-}
-const at = (entry, ...rest) => [
-    "sections",
-    entry.section,
-    "boxes",
-    entry.index,
-    ...rest,
-];
-// The boxes whose type is clear: the other rules ask nothing of a box `oneType` refused.
-function typed(config) {
-    return placed(config).flatMap((entry) => {
-        const [type] = entry.types;
-        if (type === undefined || entry.types.length !== 1)
-            return [];
-        return [{ ...entry, type, key: entry.box[type] }];
-    });
-}
-const isChart = (type) => chartTypes.includes(type);
-// Every box names exactly one type with its key.
-function oneType(config) {
-    return placed(config).flatMap((entry) => {
-        if (entry.types.length === 1)
-            return [];
-        return [
-            {
-                path: at(entry),
-                message: entry.types.length === 0
-                    ? "A box names its type and key, one of metric, line, bar, area, summary or note, like `metric: leads`."
-                    : `A box has one type; this one names ${entry.types.join(" and ")}.`,
-            },
-        ];
-    });
-}
-// Each type takes its own fields (width is `widthFits`'s).
-const fieldsOf = {
-    metric: [],
-    line: ["title", "description", "shows"],
-    bar: ["title", "description", "shows"],
-    area: ["title", "description", "shows"],
-    summary: ["title", "description", "instructions", "uses", "assignee"],
-    note: ["title", "description"],
-};
-function fieldsFit(config) {
-    return typed(config).flatMap((entry) => ["title", "description", "instructions", "shows", "uses", "assignee"]
-        .filter((field) => entry.box[field] !== undefined && !fieldsOf[entry.type].includes(field))
-        .map((field) => ({
-        path: at(entry, field),
-        message: entry.type === "metric"
-            ? `A metric box takes only its key; its ${field} belongs to metrics.${entry.key}.`
-            : `A ${entry.type} box takes ${fieldsOf[entry.type].join(", ")}; ${field} does not belong here.`,
-    })));
-}
-// Rule: keys are unique. A metric shows as a box once, and every other box has a key of its own
-// that is no metric's.
-function uniqueKeys(config) {
-    const seen = new Map();
-    return typed(config).flatMap((entry) => {
-        const first = seen.get(entry.key);
-        if (first) {
-            return [
-                {
-                    path: at(entry, entry.type),
-                    message: `The key ${entry.key} is taken by the box at sections[${first.section}].boxes[${first.index}]; every key appears once.`,
-                },
-            ];
-        }
-        seen.set(entry.key, entry);
-        if (entry.type !== "metric" && Object.hasOwn(config.metrics, entry.key)) {
-            return [
-                {
-                    path: at(entry, entry.type),
-                    message: `The key ${entry.key} is a metric's; a ${entry.type} box needs a key of its own.`,
-                },
-            ];
-        }
-        return [];
-    });
-}
-// Rule: every box refers to a key that exists.
-function refsExist(config) {
-    const boxKeys = new Set(typed(config).map((entry) => entry.key));
-    const metrics = Object.keys(config.metrics);
-    const known = metrics.length > 0 ? `the metrics are ${metrics.join(", ")}` : "there is no metric";
-    return typed(config).flatMap((entry) => {
-        if (entry.type === "metric" && !Object.hasOwn(config.metrics, entry.key)) {
-            return [
-                {
-                    path: at(entry, "metric"),
-                    message: `There is no metric ${entry.key}; ${known}. Define it under metrics first.`,
-                },
-            ];
-        }
-        const shows = (entry.box.shows ?? []).flatMap((key, i) => Object.hasOwn(config.metrics, key) || boxKeys.has(key)
-            ? []
-            : [{ path: at(entry, "shows", i), message: `There is no metric ${key}; ${known}.` }]);
-        const uses = (entry.box.uses ?? []).flatMap((key, i) => boxKeys.has(key)
-            ? []
-            : [
-                {
-                    path: at(entry, "uses", i),
-                    message: `There is no box ${key}; a summary uses boxes of its section by their key.`,
-                },
-            ]);
-        return [...shows, ...uses];
-    });
-}
-// Rule: a chart shows metrics, at least one.
-function chartsShowMetrics(config) {
-    const boxKeys = new Set(typed(config).map((entry) => entry.key));
-    return typed(config).flatMap((entry) => {
-        if (!isChart(entry.type))
-            return [];
-        const shows = entry.box.shows ?? [];
-        if (shows.length === 0) {
-            return [
-                {
-                    path: at(entry, "shows"),
-                    message: `A ${entry.type} chart shows at least one metric, like shows: [leads].`,
-                },
-            ];
-        }
-        return shows.flatMap((key, i) => !Object.hasOwn(config.metrics, key) && boxKeys.has(key)
-            ? [
-                {
-                    path: at(entry, "shows", i),
-                    message: `${key} is a box, not a metric; a chart shows metrics.`,
-                },
-            ]
-            : []);
-    });
-}
-// Rule: a summary uses only boxes of its own section, and never itself.
-function usesOwnSection(config) {
-    const boxes = typed(config);
-    return boxes.flatMap((entry) => (entry.box.uses ?? []).flatMap((key, i) => {
-        if (key === entry.key) {
-            return [{ path: at(entry, "uses", i), message: "A summary cannot use itself." }];
-        }
-        const home = boxes.filter((other) => other.key === key);
-        // Unknown is `refsExist`'s; a key written twice is `uniqueKeys`', so one in the own section
-        // is enough here.
-        if (home.length === 0 || home.some((other) => other.section === entry.section))
-            return [];
-        const section = home[0]?.section;
-        return [
-            {
-                path: at(entry, "uses", i),
-                message: `${key} is a box of section ${section} (${config.sections[section]?.title}); a summary uses only boxes of its own section.`,
-            },
-        ];
-    }));
-}
-// Rule: width only on a summary or a note (its range is the field's own check).
-function widthFits(config) {
-    return typed(config).flatMap((entry) => entry.box.width !== undefined && entry.type !== "summary" && entry.type !== "note"
-        ? [
-            {
-                path: at(entry, "width"),
-                message: `width is only for a summary or a note; a metric is 1 wide, a chart 2, a section 3. Leave it out of this ${entry.type} box.`,
-            },
-        ]
-        : []);
-}
-// Rule: a note has a description, its visible text.
-function noteHasDescription(config) {
-    return typed(config).flatMap((entry) => entry.type === "note" && !entry.box.description?.trim()
-        ? [
-            {
-                path: at(entry, "description"),
-                message: "A note shows its description; write the note's text there.",
-            },
-        ]
-        : []);
-}
-// Rule: a summary has instructions (a metric's are required by its own schema).
-function summaryHasInstructions(config) {
-    return typed(config).flatMap((entry) => entry.type === "summary" && !entry.box.instructions?.trim()
-        ? [
-            {
-                path: at(entry, "instructions"),
-                message: "A summary needs instructions: what the Operator writes in it each run.",
-            },
-        ]
-        : []);
-}
-const configRules = [
-    oneType,
-    fieldsFit,
-    uniqueKeys,
-    refsExist,
-    chartsShowMetrics,
-    usesOwnSection,
-    widthFits,
-    noteHasDescription,
-    summaryHasInstructions,
-];
-export const DashboardConfig = z
-    .strictObject({
-    instruction: z
-        .string()
-        .max(200_000)
-        .optional()
-        .describe("The dashboard's instruction, Markdown: what the dashboard is about and how every AI filling it goes about it (E87). It comes along with every read of the dashboard over MCP; the instructions of a metric or a summary stay for the single entry. Leaving it out, or an empty text, means none."),
-    schedule: Schedule.default({ rhythm: "manual" }).describe("When a run falls due (Ausführung). Leaving it out is manual."),
-    metrics: z
-        .record(DashboardKey, DashboardMetric)
-        .default({})
-        .describe("Every metric once, under its fixed key, in the order of the table's columns: title, description, instructions, source, assignee."),
-    sections: z
-        .array(DashboardSection)
-        .max(30)
-        .default([])
-        .describe("The sections from top to bottom, each with its boxes in reading order."),
-})
-    .superRefine((config, ctx) => {
-    for (const rule of configRules) {
-        for (const finding of rule(config))
-            ctx.addIssue({ code: "custom", ...finding });
-    }
-});
-// ---------------------------------------------------------------------------------------------
-// A run: the filled-in template (Funktionen › Läufe). Whether it fits ITS configuration (every
-// metric and summary once, no unknown key) is asked by `validateRun` in `intelligence`.
-const ReportText = z
-    .string({ error: "report is text: a sentence on what is missing or wrong." })
-    .max(10_000)
-    .nullable()
-    .optional()
-    .describe("Only when something is missing or wrong: what, in a sentence. Leave it out otherwise.");
-const RecommendationText = z
-    .string({ error: "recommendation is text: how the instructions could become clearer." })
-    .max(10_000)
-    .nullable()
-    .optional()
-    .describe("Only with a report: how the instructions could become clearer.");
-const DashboardRunMetric = z
-    .strictObject({
-    value: z
-        .union([z.number(), z.string().max(1_000), z.null()], {
-        error: (issue) => issue.input === undefined
-            ? "value is required: the number or text, or ~ (null) when it is missing, then with a report."
-            : "value is a number, a short text, or ~ (null).",
-    })
-        .describe("The metric's value in this run: a number, a short text, or null when missing."),
-    source: z
-        .string({
-        error: (issue) => issue.input === undefined
-            ? "source is required: the Colab node (colab://node_…) or the tool the value came from, or ~ (null)."
-            : "source is text: a Colab node as colab://node_… or a tool name.",
-    })
-        .max(2_000)
-        .nullable()
-        .describe("Where the value came from: a Colab node as colab://node_… (its id, which intelligence_node_list answers), or the tool called, with parameter."),
-    parameter: z
-        .record(z.string(), z.unknown())
-        .optional()
-        .describe("The parameters of the tool named in source, so the value can be checked."),
-    report: ReportText,
-    recommendation: RecommendationText,
-})
-    .describe("One metric of the run.");
-const DashboardRunSummary = z
-    .strictObject({
-    text: z
-        .string({
-        error: (issue) => issue.input === undefined
-            ? "text is required: the summary, or ~ (null) when it could not be written, then with a report."
-            : "text is the summary as text.",
-    })
-        .max(20_000)
-        .nullable()
-        .describe("The summary the instructions ask for, or null when it could not be written."),
-    report: ReportText,
-    recommendation: RecommendationText,
-})
-    .describe("One summary of the run.");
-export const DashboardRun = z
-    .strictObject({
-    metrics: z
-        .record(DashboardKey, DashboardRunMetric)
-        .default({})
-        .describe("Every metric of the configuration once, under its key."),
-    summaries: z
-        .record(DashboardKey, DashboardRunSummary)
-        .default({})
-        .describe("Every summary of the configuration once, under its key."),
-})
-    .describe("A run of a dashboard as the Operator fills in its template.");
-// ---------------------------------------------------------------------------------------------
-// The tools.
-const Name = z.string().max(200);
-const config = z
-    .record(z.string(), z.unknown())
-    .optional()
-    .describe("The configuration as an object, the way the UI sends it, in the shape intelligence_dashboard_get answers: instruction, schedule, metrics, sections. Send exactly one of config and yaml.");
-const yaml = z
-    .string()
-    .max(200_000)
-    .optional()
-    .describe("The configuration as YAML text: instruction (the dashboard's Markdown for every AI, optional), schedule (rhythm, days, dayOfMonth, times, dates, zone, whileOpen), metrics (each once under a fixed key: title, description, instructions, source, assignee) and sections (title, description, boxes written as `metric: leads`, `line: trend` with shows, `summary: verdict` with instructions, uses and assignee, `note: hint` with description). Send exactly one of config and yaml.");
-export const DashboardCreateInput = z.strictObject({
-    // ⚠️ Required and nullable (trap C015): null is the top level of Shared.
-    parentId: NodeId.nullable().describe("The folder to create the dashboard in, one you can write to; null creates it on the top level of Shared, visible to you until you share it."),
-    name: Name.describe("The dashboard's name as people read it."),
-    config,
-    yaml,
-    idempotencyKey: IdempotencyKey,
-});
-export const DashboardGetInput = z.strictObject({ dashboardId: DashboardId });
-export const DashboardUpdateInput = z.strictObject({
-    dashboardId: DashboardId,
-    rev: Rev,
-    config: config.describe("The whole new configuration as an object, replacing the old one. Send exactly one of config and yaml."),
-    yaml: yaml.describe("The whole new configuration as YAML text, replacing the old one; read it from intelligence_dashboard_get, change it, send it back. Send exactly one of config and yaml."),
-});
-export const DashboardDetail = z.object({
-    dashboardId: DashboardId,
-    name: z.string(),
-    config: DashboardConfig,
-    yaml: z.string(),
-    // The next moment a run falls due (#43), null when manual or every date has passed.
-    nextRunAt: z.iso.datetime().nullable(),
-    // The moment a run is owed for now (passed, unanswered, no run open), else null.
-    dueAt: z.iso.datetime().nullable(),
-    // Whether a machine (an Operator) can write on it: a schedule other than manual needs one (#334).
-    processCheck: z.object({ operator: z.boolean() }),
-    rights: z.object({ write: z.boolean() }),
-    rev: z.number().int(),
-    updatedAt: z.iso.datetime(),
-});