@engenty/wizards-runtime 0.0.0-stage → 0.7.5

package/apps/runtime/dist/plugins/runs.js

@@ -0,0 +1,210 @@
+import { createHash } from "node:crypto";
+import { LANGS, textLang, wizardLang } from "@engenty-wizards/shared/definition";
+import { noteText } from "@engenty-wizards/shared/run";
+import { and, asc, eq, inArray, isNotNull } from "drizzle-orm";
+import { db, schema, withTenant } from "../db/client.js";
+import { answerAsk } from "../engine/asks.js";
+import { watchRun } from "../engine/events.js";
+import { fieldErrorsIn } from "../engine/input.js";
+import { cancel, createRun, goBack, NoCreditsError, RunInputError, retry, reviewStep, submitPage, } from "../engine/runner.js";
+import { saveAsset } from "../files/storage.js";
+import { wizardUnavailable } from "../limits.js";
+import { transcribeAudio } from "../media/transcribe.js";
+import { errorText, ModelUnavailableError } from "../model-errors.js";
+import { uploadMime } from "../routes/delivery.js";
+import { runTicket } from "../secrets/signing.js";
+import { notFound, ServiceError } from "../services/errors.js";
+import { runnerSettingsOf, runnersOf } from "../services/runners.js";
+import { pluginRun, refusedInput, runReportOf, waitRun } from "../services/runs.js";
+import { shareUrl } from "../services/wizards.js";
+import { visitorOverLimit } from "../tenants/control.js";
+import { currentTenant } from "../tenants/tenant.js";
+/**
+ * `wizards.server.runs`: the functions behind the MCP tools, for a plugin's door. A run started
+ * here is a live run of the published wizard for a person of that door; the plugin keeps who
+ * the person is, the runtime keeps a hash of it as the run's visitor, so what the wizard
+ * remembers is theirs on the run page too.
+ */
+/** A person of a door as the run's visitor: a hash, never the number or the account itself. */
+function visitorOf(person) {
+    return `p:${createHash("sha256").update(`${person.channel}:${person.id}`).digest("hex").slice(0, 32)}`;
+}
+export function runsApiFor(pluginId) {
+    return {
+        async start(input) {
+            const w = await db.query.wizard.findFirst({
+                where: and(eq(schema.wizard.tenantId, currentTenant()), "token" in input
+                    ? eq(schema.wizard.shareToken, input.token)
+                    : eq(schema.wizard.id, input.wizardId)),
+            });
+            if (!w || w.publishedVersion === null) {
+                throw notFound();
+            }
+            const version = await db.query.wizardVersion.findFirst({
+                where: and(eq(schema.wizardVersion.wizardId, w.id), eq(schema.wizardVersion.version, w.publishedVersion)),
+            });
+            if (!version) {
+                throw notFound();
+            }
+            const reason = await wizardUnavailable(w);
+            if (reason) {
+                throw new ServiceError("refused", noteText(reason, wizardLang(version.definition)));
+            }
+            const visitorId = visitorOf(input.person);
+            if (await visitorOverLimit(visitorId, null)) {
+                throw new ServiceError("refused", noteText({ code: "tooManyRuns" }, wizardLang(version.definition)));
+            }
+            const runId = await createRun({
+                wizardId: w.id,
+                definition: version.definition,
+                files: version.files,
+                version: w.publishedVersion,
+                mode: "live",
+                visitorId,
+                runner: input.runner ?? pluginId,
+            }).catch((err) => {
+                if (err instanceof ModelUnavailableError) {
+                    throw new ServiceError("refused", errorText(err, textLang(wizardLang(version.definition))));
+                }
+                if (err instanceof NoCreditsError) {
+                    throw new ServiceError("no_credits", noteText({ code: "wizardRunOutCredits" }, wizardLang(version.definition)));
+                }
+                throw err;
+            });
+            const first = version.definition.steps[0];
+            let refused = null;
+            if (first?.type === "page" && input.answers && Object.keys(input.answers).length) {
+                const answers = input.answers;
+                const values = Object.fromEntries(first.fields.filter((f) => f.id in answers).map((f) => [f.id, answers[f.id]]));
+                try {
+                    await submitPage(runId, first.id, values);
+                }
+                catch (err) {
+                    if (!(err instanceof RunInputError)) {
+                        throw err;
+                    }
+                    refused = fieldErrorsIn(err.errors, "en");
+                }
+            }
+            return { runId, ticket: runTicket(runId), refused };
+        },
+        async report(runId, options) {
+            const run = await waitRun(() => pluginRun(runId), options?.waitSeconds ?? 0);
+            return (await runReportOf(run, options?.draft));
+        },
+        async wizards(runner) {
+            const rows = await db.query.wizard.findMany({
+                where: and(eq(schema.wizard.tenantId, currentTenant()), isNotNull(schema.wizard.publishedVersion)),
+                orderBy: asc(schema.wizard.createdAt),
+            });
+            const available = await runnersOf();
+            const offered = rows.filter((w) => runnerSettingsOf(w, available).enabled.includes(runner));
+            const versions = offered.length
+                ? await db.query.wizardVersion.findMany({
+                    where: inArray(schema.wizardVersion.wizardId, offered.map((w) => w.id)),
+                })
+                : [];
+            return offered.flatMap((w) => {
+                const version = versions.find((v) => v.wizardId === w.id && v.version === w.publishedVersion);
+                return version
+                    ? [
+                        {
+                            wizardId: w.id,
+                            token: w.shareToken,
+                            title: version.definition.title,
+                            lang: textLang(wizardLang(version.definition)),
+                        },
+                    ]
+                    : [];
+            });
+        },
+        async answerPage(runId, stepId, values) {
+            await pluginRun(runId);
+            await submitPage(runId, stepId, values).catch(refusedInput);
+        },
+        async review(runId, stepId, action) {
+            await pluginRun(runId);
+            await reviewStep(runId, stepId, action).catch(refusedInput);
+        },
+        async answerAsk(runId, askId, answer) {
+            const run = await pluginRun(runId);
+            if (!(await answerAsk(runId, askId, answer === "allow" ? { type: "done" } : { type: "skip" }))) {
+                throw new ServiceError("refused", noteText({ code: "askClosed" }, wizardLang(run.definition)));
+            }
+        },
+        async control(runId, action) {
+            await pluginRun(runId);
+            const command = { back: goBack, retry, cancel }[action];
+            await command(runId).catch(refusedInput);
+        },
+        subscribe(runId, listener) {
+            // The listener runs inside the tenant the subscription was made in, as the events do.
+            const tenantId = currentTenant();
+            // Changes the runner makes in another process reach the plugin too, each event once.
+            return watchRun(runId, (signal) => {
+                const event = signal.event;
+                const shaped = {
+                    runId,
+                    event: event
+                        ? {
+                            id: event.id,
+                            at: event.at,
+                            stepId: event.stepId,
+                            type: event.type,
+                            message: event.message,
+                            note: event.note
+                                ? {
+                                    code: event.note.code,
+                                    text: Object.fromEntries(LANGS.map((lang) => [lang, noteText(event.note, lang)])),
+                                }
+                                : null,
+                        }
+                        : null,
+                };
+                void withTenant(tenantId, () => listener(shaped));
+            });
+        },
+        async handoffUrl(runId) {
+            const run = await pluginRun(runId);
+            const w = await db.query.wizard.findFirst({ where: eq(schema.wizard.id, run.wizardId) });
+            if (!w) {
+                throw notFound();
+            }
+            return `${shareUrl(w.shareToken)}/${run.id}?rt=${encodeURIComponent(runTicket(run.id))}`;
+        },
+        async upload(runId, file) {
+            await pluginRun(runId);
+            // The type comes from the channel's sender: kept only when it is one a wizard takes.
+            const mime = uploadMime(file.mime);
+            const asset = await saveAsset({
+                runId,
+                kind: mime.startsWith("image/") ? "image" : "file",
+                mime,
+                name: file.name,
+                data: file.data instanceof Uint8Array ? file.data : new Uint8Array(file.data),
+            });
+            return { assetId: asset.id };
+        },
+        async transcribe(runId, file) {
+            const run = await pluginRun(runId);
+            if (run.status === "done" || run.status === "cancelled" || run.status === "failed") {
+                throw new ServiceError("refused", noteText({ code: "runOver" }, wizardLang(run.definition)));
+            }
+            const bytes = file.data instanceof Uint8Array ? file.data : new Uint8Array(file.data);
+            if (!bytes.length || bytes.length > 10_000_000) {
+                throw new ServiceError("invalid", noteText({ code: "recordingTooLarge" }, wizardLang(run.definition)));
+            }
+            const { text } = await transcribeAudio({
+                bytes,
+                mediaType: file.mime.split(";")[0].trim() || "audio/ogg",
+                call: { runId: run.id },
+            }).catch((err) => {
+                if (err instanceof ModelUnavailableError) {
+                    throw new ServiceError("refused", errorText(err, textLang(wizardLang(run.definition))));
+                }
+                throw err;
+            });
+            return { text };
+        },
+    };
+}

package/apps/runtime/dist/render/browser-path.js

@@ -0,0 +1,54 @@
+import { accessSync, constants, existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { delimiter, join } from "node:path";
+/** The first executable called `name` in the folders of `path` (a PATH value). */
+export function findOnPath(name, path) {
+    for (const dir of path.split(delimiter)) {
+        if (!dir) {
+            continue;
+        }
+        const file = join(dir, name);
+        try {
+            accessSync(file, constants.X_OK);
+            return file;
+        }
+        catch {
+            // not here
+        }
+    }
+    return null;
+}
+/**
+ * The browser the runtime renders PDF and PNG with and drives for websites: `CHROME_PATH`, else
+ * the first Chromium-based browser installed (Chrome, Edge, Chromium, Brave). The setup and
+ * `wizards doctor` report this one, and env.ts starts it, so a browser they show is the one used.
+ */
+export function findChrome(env = process.env) {
+    if (env.CHROME_PATH) {
+        return existsSync(env.CHROME_PATH) ? env.CHROME_PATH : null;
+    }
+    if (process.platform === "darwin") {
+        const apps = [
+            "Google Chrome.app/Contents/MacOS/Google Chrome",
+            "Microsoft Edge.app/Contents/MacOS/Microsoft Edge",
+            "Chromium.app/Contents/MacOS/Chromium",
+            "Brave Browser.app/Contents/MacOS/Brave Browser",
+        ];
+        const roots = ["/Applications", join(homedir(), "Applications")];
+        for (const app of apps) {
+            for (const root of roots) {
+                if (existsSync(join(root, app))) {
+                    return join(root, app);
+                }
+            }
+        }
+        return null;
+    }
+    for (const name of ["google-chrome", "chromium", "chromium-browser", "microsoft-edge"]) {
+        const file = findOnPath(name, env.PATH ?? "");
+        if (file) {
+            return file;
+        }
+    }
+    return null;
+}

package/apps/runtime/dist/render/chromium.js

@@ -0,0 +1,98 @@
+import { chromium } from "playwright-core";
+import { env } from "../env.js";
+import { assertPublicUrl } from "../tools/net-guard.js";
+/**
+ * One Chromium for the whole server: the engenty-browser container over CDP when
+ * `BROWSER_CDP_URL` is set, else a local headless Chrome. Every user of it opens
+ * its own context, so runs never share cookies or storage. Service workers are blocked: their
+ * requests would not pass a context's route guard.
+ */
+let browserPromise = null;
+async function connect() {
+    const browser = env.browserCdpUrl
+        ? await chromium.connectOverCDP(env.browserCdpUrl)
+        : await chromium.launch({
+            executablePath: env.chromePath,
+            headless: true,
+            args: ["--no-sandbox", "--disable-dev-shm-usage", "--font-render-hinting=none"],
+        });
+    browser.on("disconnected", () => {
+        browserPromise = null;
+    });
+    return browser;
+}
+export function getBrowser() {
+    if (!browserPromise) {
+        browserPromise = connect().catch((err) => {
+            browserPromise = null;
+            throw err;
+        });
+    }
+    return browserPromise;
+}
+export async function newContext(options = {}) {
+    const browser = await getBrowser();
+    return browser.newContext({
+        viewport: { width: 1280, height: 900 },
+        serviceWorkers: "block",
+        ...options,
+    });
+}
+/**
+ * Verdicts are kept only briefly: a name's addresses can change, and a page that rebinds its own
+ * name to a private address must not ride on an old "public".
+ */
+const HOST_CHECK_TTL_MS = 30_000;
+const hostChecks = new Map();
+function publicHost(url) {
+    let host;
+    try {
+        host = new URL(url).host;
+    }
+    catch {
+        return Promise.resolve(false);
+    }
+    const now = Date.now();
+    const cached = hostChecks.get(host);
+    if (cached && now - cached.at < HOST_CHECK_TTL_MS) {
+        return cached.check;
+    }
+    const check = assertPublicUrl(url).then(() => true, () => false);
+    hostChecks.set(host, { at: now, check });
+    if (hostChecks.size > 2000) {
+        hostChecks.clear();
+    }
+    return check;
+}
+/**
+ * A context for browsing the web on a person's behalf: every request, whoever started it (the
+ * agent, a redirect, the person clicking), may only reach public hosts over http(s). Pages may
+ * still use their own data: and blob: URLs; every other scheme (file:, ftp:, ...) is refused.
+ */
+export async function webContext(options = {}) {
+    const context = await newContext({ acceptDownloads: true, ...options });
+    await context.route("**/*", async (route) => {
+        const url = route.request().url();
+        if (/^(data|blob):/i.test(url) || (/^https?:/i.test(url) && (await publicHost(url)))) {
+            await route.continue();
+        }
+        else {
+            await route.abort("blockedbyclient");
+        }
+    });
+    return context;
+}
+/**
+ * A context for rendering generated HTML: every network request is refused. The HTML is
+ * self-contained by design, and nothing it runs may reach the server's network.
+ */
+export async function offlineContext(options = {}) {
+    const context = await newContext({ javaScriptEnabled: true, ...options });
+    await context.route("**/*", (route) => route.abort("blockedbyclient"));
+    return context;
+}
+export async function closeBrowser() {
+    const b = await browserPromise?.catch(() => null);
+    browserPromise = null;
+    await b?.close().catch(() => undefined);
+}

package/apps/runtime/dist/render/convert.js

@@ -0,0 +1,158 @@
+import HTMLtoDOCX from "@turbodocx/html-to-docx";
+import ExcelJS from "exceljs";
+import { marked } from "marked";
+import TurndownService from "turndown";
+import { offlineContext } from "./chromium.js";
+const turndown = new TurndownService({ headingStyle: "atx", codeBlockStyle: "fenced" });
+export const MIME = {
+    png: "image/png",
+    mp4: "video/mp4",
+    mp3: "audio/mpeg",
+    pdf: "application/pdf",
+    docx: "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+    html: "text/html",
+    md: "text/markdown",
+    txt: "text/plain",
+    csv: "text/csv",
+    xlsx: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+    json: "application/json",
+    zip: "application/zip",
+};
+/** A calm print stylesheet for documents written as Markdown. */
+export function markdownToHtml(markdown, title = "Document") {
+    const body = marked.parse(markdown, { async: false });
+    return `<!doctype html><html><head><meta charset="utf-8"><title>${escapeHtml(title)}</title>
+<style>
+  @page { size: A4; margin: 22mm 20mm; }
+  body { font-family: "Inter", "Helvetica Neue", Arial, sans-serif; color: #1d1a17; line-height: 1.55; font-size: 11pt; max-width: 760px; margin: 40px auto; padding: 0 24px; }
+  h1 { font-size: 22pt; line-height: 1.2; margin: 0 0 12pt; }
+  h2 { font-size: 14pt; margin: 22pt 0 6pt; }
+  h3 { font-size: 12pt; margin: 16pt 0 4pt; }
+  table { border-collapse: collapse; width: 100%; margin: 10pt 0; font-size: 10pt; }
+  th, td { border-bottom: 1px solid #e6e1da; padding: 6pt 8pt; text-align: left; vertical-align: top; }
+  th { font-weight: 600; background: #f7f4ef; }
+  a { color: #b4532a; }
+  blockquote { border-left: 3px solid #e6e1da; margin: 0; padding-left: 12pt; color: #5d564e; }
+  code { background: #f4f1ec; padding: 1px 4px; border-radius: 3px; }
+  @media print { body { margin: 0; padding: 0; max-width: none; } }
+</style></head><body>${body}</body></html>`;
+}
+export function escapeHtml(s) {
+    return s.replace(/[&<>"']/g, (c) => `&#${c.charCodeAt(0)};`);
+}
+export function htmlToMarkdown(html) {
+    const body = html.match(/<body[^>]*>([\s\S]*)<\/body>/i)?.[1] ?? html;
+    return turndown.turndown(body.replace(/<style[\s\S]*?<\/style>/gi, "").replace(/<script[\s\S]*?<\/script>/gi, ""));
+}
+export async function htmlToPdf(html) {
+    const context = await offlineContext();
+    try {
+        const page = await context.newPage();
+        await page.setContent(html, { waitUntil: "networkidle", timeout: 30_000 });
+        return await page.pdf({ format: "A4", printBackground: true, preferCSSPageSize: true });
+    }
+    finally {
+        await context.close();
+    }
+}
+export async function htmlToPng(html, width = 1200, opts = {}) {
+    const context = await offlineContext({
+        viewport: { width, height: opts.height ?? 900 },
+        deviceScaleFactor: opts.scale ?? 2,
+    });
+    try {
+        const page = await context.newPage();
+        await page.setContent(html, { waitUntil: "networkidle", timeout: 30_000 });
+        return await page.screenshot({ fullPage: opts.fullPage ?? true, type: "png" });
+    }
+    finally {
+        await context.close();
+    }
+}
+export async function htmlToDocx(html) {
+    const cleaned = html.replace(/<script[\s\S]*?<\/script>/gi, "");
+    const out = await HTMLtoDOCX(cleaned, null, {
+        table: { row: { cantSplit: true } },
+        font: "Arial",
+    });
+    if (out instanceof ArrayBuffer) {
+        return new Uint8Array(out);
+    }
+    if (typeof Blob !== "undefined" && out instanceof Blob) {
+        return new Uint8Array(await out.arrayBuffer());
+    }
+    return new Uint8Array(out);
+}
+/** The first array of objects inside a JSON value — the table a step produced. */
+export function firstTable(value) {
+    if (Array.isArray(value) && value.every((r) => r && typeof r === "object" && !Array.isArray(r))) {
+        return value;
+    }
+    if (value && typeof value === "object") {
+        for (const v of Object.values(value)) {
+            const t = firstTable(v);
+            if (t) {
+                return t;
+            }
+        }
+    }
+    return null;
+}
+function tableColumns(rows) {
+    return [...new Set(rows.flatMap((r) => Object.keys(r)))];
+}
+function cell(v) {
+    return v === null || v === undefined ? "" : typeof v === "object" ? JSON.stringify(v) : String(v);
+}
+export function tableToCsv(rows) {
+    const cols = tableColumns(rows);
+    const esc = (s) => (/[",\n;]/.test(s) ? `"${s.replace(/"/g, '""')}"` : s);
+    return [
+        cols.map(esc).join(","),
+        ...rows.map((r) => cols.map((c) => esc(cell(r[c]))).join(",")),
+    ].join("\n");
+}
+/** Every table of a step's JSON result, by its key; a bare array is the one table "Data". */
+export function allTables(value) {
+    const isTable = (v) => Array.isArray(v) &&
+        v.length > 0 &&
+        v.every((r) => r && typeof r === "object" && !Array.isArray(r));
+    if (isTable(value)) {
+        return [{ name: "Data", rows: value }];
+    }
+    if (!value || typeof value !== "object") {
+        return [];
+    }
+    return Object.entries(value).flatMap(([name, v]) => isTable(v)
+        ? [{ name, rows: v }]
+        : Array.isArray(v) && v.length && v.every((x) => typeof x !== "object")
+            ? [{ name, rows: v.map((x) => ({ [name]: x })) }]
+            : []);
+}
+/** A workbook with one sheet per table. `headers` renames columns (column id → label). */
+export async function tablesToXlsx(tables) {
+    const wb = new ExcelJS.Workbook();
+    for (const [index, table] of tables.entries()) {
+        const ws = wb.addWorksheet(table.name.replace(/[\\/*?:[\]]/g, " ").slice(0, 31) || `Sheet${index + 1}`);
+        const cols = table.headers ? Object.keys(table.headers) : tableColumns(table.rows);
+        ws.columns = cols.map((c) => {
+            const header = table.headers?.[c] ?? c;
+            return { header, key: c, width: Math.min(40, Math.max(12, header.length + 4)) };
+        });
+        for (const r of table.rows) {
+            ws.addRow(Object.fromEntries(cols.map((c) => [c, typeof r[c] === "number" ? r[c] : cell(r[c])])));
+        }
+        ws.getRow(1).font = { bold: true };
+    }
+    return new Uint8Array(await wb.xlsx.writeBuffer());
+}
+export function jsonToMarkdown(value) {
+    const rows = firstTable(value);
+    if (rows?.length) {
+        const cols = tableColumns(rows);
+        const head = `| ${cols.join(" | ")} |\n| ${cols.map(() => "---").join(" | ")} |`;
+        const body = rows.map((r) => `| ${cols.map((c) => cell(r[c]).replace(/\|/g, "\\|")).join(" | ")} |`);
+        return [head, ...body].join("\n");
+    }
+    return `\`\`\`json\n${JSON.stringify(value, null, 2)}\n\`\`\``;
+}