@engenty/wizards-runtime 0.7.11 → 0.9.0

package/apps/runtime/dist/sharing/index.js

@@ -0,0 +1,298 @@
+import { and, desc, eq } from "drizzle-orm";
+import { listConnectors, resolveConnector } from "../connectors/external.js";
+import { connectionViews, connectorOptions, registerConnectionSource, } from "../connectors/index.js";
+import { db, schema } from "../db/client.js";
+import { renderTemplate } from "../engine/template.js";
+import { scopeOf } from "../store/index.js";
+import { currentTenant } from "../tenants/tenant.js";
+import { resultStepOf, resultText } from "./files.js";
+import { shareJobs } from "./state.js";
+import { browserTarget } from "./targets/browser.js";
+import { canPublish, connectorTarget } from "./targets/connector.js";
+import { emailTarget } from "./targets/email.js";
+import { slackTarget } from "./targets/slack.js";
+import { storageConnectors, storageTarget } from "./targets/storage.js";
+import { sayIn } from "./types.js";
+/**
+ * The share targets of this runtime. The fixed ones are listed here; every connector that
+ * stores files adds `storage:<connector>`, every connector that can write `connector:<connector>`.
+ * To add a target, write it in `./targets` and name it here.
+ */
+const FIXED = [emailTarget, slackTarget, browserTarget];
+/** A share target by its id; null when this project has none of that name. */
+export async function shareTarget(projectId, id) {
+    const fixed = FIXED.find((t) => t.id === id);
+    if (fixed) {
+        return fixed;
+    }
+    const cut = id.indexOf(":");
+    const [kind, connectorId] = [id.slice(0, cut), id.slice(cut + 1)];
+    if (kind === "storage") {
+        const connector = storageConnectors().find((c) => c.id === connectorId);
+        return connector ? storageTarget(connector) : null;
+    }
+    if (kind === "connector") {
+        const found = await resolveConnector(projectId, connectorId);
+        return found && canPublish(found.connector)
+            ? connectorTarget(found.connector, found.imported)
+            : null;
+    }
+    return null;
+}
+/** Every target of a project, in the order a result shows them. */
+async function projectTargets(projectId) {
+    const imported = (await listConnectors(projectId)).filter((c) => c.sourceKind !== "builtin");
+    const through = await Promise.all(imported.map((c) => shareTarget(projectId, `connector:${c.id}`)));
+    return [
+        emailTarget,
+        ...storageConnectors().flatMap((c) => storageTarget(c) ?? []),
+        slackTarget,
+        ...through.filter((t) => Boolean(t)),
+        browserTarget,
+    ];
+}
+/**
+ * Every target a wizard of the project can name on its result, for the editor and for whoever
+ * authors a wizard: the default ones, and one for each built-in connector that can write.
+ */
+export async function projectShareTargets(projectId, lang) {
+    const targets = await projectTargets(projectId);
+    const builtin = (await listConnectors(projectId)).filter((c) => c.sourceKind === "builtin");
+    for (const connector of builtin) {
+        const target = await shareTarget(projectId, `connector:${connector.id}`);
+        if (target) {
+            targets.push(target);
+        }
+    }
+    return Promise.all(targets.map(async (target) => ({
+        id: target.id,
+        name: sayIn(lang, target.name),
+        description: sayIn(lang, target.description),
+        icon: target.icon,
+        agent: Boolean(target.agent),
+        usable: await offerable(target, projectId),
+        byDefault: target.byDefault !== false,
+        fields: target.fields.map((f) => ({ id: f.id, label: sayIn(lang, f.label), kind: f.kind })),
+    })));
+}
+/** Whether a target can work here right now: what it drives is there, its account can be connected. */
+async function offerable(target, projectId) {
+    if (target.available && !(await target.available())) {
+        return false;
+    }
+    const connection = target.connection?.();
+    return !connection || (await connectorOptions(connection, projectId)).length > 0;
+}
+/**
+ * The targets a result names: its own list, else every target of the project a result offers
+ * by default. `missing` names listed targets this project does not have.
+ */
+async function namedTargets(run, projectId) {
+    const result = resultStepOf(run);
+    if (!result) {
+        return { entries: [], listed: true, missing: [] };
+    }
+    if (!result.share) {
+        const entries = (await projectTargets(projectId))
+            .filter((target) => target.byDefault !== false)
+            .map((target) => ({ key: target.id, target, values: {} }));
+        return { entries, listed: false, missing: [] };
+    }
+    const entries = [];
+    const missing = [];
+    for (const [i, option] of result.share.entries()) {
+        const target = await shareTarget(projectId, option.target);
+        if (target) {
+            entries.push({
+                key: `${i}:${option.target}`,
+                target,
+                label: option.label,
+                values: option.values ?? {},
+            });
+        }
+        else {
+            missing.push(option.label ?? option.target);
+        }
+    }
+    return { entries, listed: true, missing };
+}
+/**
+ * The targets a finished run offers. A wizard that lists them on its result decides; else every
+ * target that needs no model is offered, and the ones an agent drives only to the wizard's owner
+ * — they run on the wizard's credits.
+ */
+export async function offeredTargets(run, projectId, member) {
+    const { entries, listed } = await namedTargets(run, projectId);
+    const asked = entries.filter((e) => listed || !e.target.agent || member);
+    const usable = await Promise.all(asked.map((e) => offerable(e.target, projectId)));
+    return asked.filter((_, i) => usable[i]);
+}
+export function targetScope(run, projectId, lang) {
+    const result = resultStepOf(run);
+    return {
+        run,
+        projectId,
+        lang,
+        title: [result?.title, run.definition.title].filter(Boolean).join(" · "),
+        message: result?.message ?? null,
+        text: resultText(run),
+    };
+}
+async function templateScope(run, projectId) {
+    const project = await db.query.project.findFirst({ where: eq(schema.project.id, projectId) });
+    return {
+        def: run.definition,
+        state: run.state,
+        brand: project?.brand ?? {},
+    };
+}
+async function targetView(entry, scope, templates) {
+    const { target } = entry;
+    const { lang } = scope;
+    const connection = target.connection?.() ?? null;
+    const [account] = connection
+        ? await connectionViews([connection], scopeOf(scope.run), scope.projectId, lang)
+        : [null];
+    const defaults = (await target.defaults?.(scope)) ?? {};
+    return {
+        key: entry.key,
+        target: target.id,
+        name: entry.label ?? sayIn(lang, target.name),
+        description: sayIn(lang, target.description),
+        icon: target.icon,
+        connection: account,
+        fields: target.fields.map((f) => ({
+            ...f,
+            label: sayIn(lang, f.label),
+            placeholder: f.placeholder && sayIn(lang, f.placeholder),
+            help: f.help && sayIn(lang, f.help),
+            value: entry.values[f.id] !== undefined
+                ? renderTemplate(entry.values[f.id], templates)
+                : (defaults[f.id] ?? ""),
+        })),
+        takes: target.takes,
+        agent: Boolean(target.agent),
+        presets: (target.presets ?? []).map((p) => ({
+            label: p.label,
+            values: Object.fromEntries(Object.entries(p.values).map(([id, v]) => [id, sayIn(lang, v)])),
+        })),
+    };
+}
+/** What the share sheet shows: the targets of this result and what was sent before. */
+export async function shareOverview(run, projectId, member, lang) {
+    const scope = targetScope(run, projectId, lang);
+    const templates = await templateScope(run, projectId);
+    const offered = await offeredTargets(run, projectId, member);
+    const jobs = await shareJobs(run.id);
+    return {
+        targets: await Promise.all(offered.map((entry) => targetView(entry, scope, templates))),
+        jobs,
+    };
+}
+const PLACEHOLDER = /\{\{\s*([^}]+?)\s*\}\}/g;
+/** The placeholders of prefilled values that come out empty. */
+function emptyPlaceholders(values, templates) {
+    const empty = new Set();
+    for (const value of Object.values(values)) {
+        for (const [whole, ref] of value.matchAll(PLACEHOLDER)) {
+            if (!renderTemplate(whole, templates).trim()) {
+                empty.add(ref.trim());
+            }
+        }
+    }
+    return [...empty];
+}
+/** How much of a written deliverable the preview shows. */
+const EXCERPT = 1500;
+/** A run that never happened, for a wizard without a finished test run: the draft, no answers. */
+function standIn(wizard, userId) {
+    const now = new Date();
+    return {
+        id: `preview-${wizard.id}`,
+        wizardId: wizard.id,
+        tenantId: wizard.tenantId,
+        definition: wizard.draft,
+        files: [],
+        version: null,
+        mode: "test",
+        runner: null,
+        lang: null,
+        visitorId: null,
+        userId,
+        ipHash: null,
+        origin: null,
+        client: null,
+        status: "done",
+        cursor: null,
+        state: { values: {}, outputs: {}, history: [], notes: {} },
+        error: null,
+        ask: null,
+        answer: null,
+        unattended: false,
+        deviceOffer: null,
+        costMicros: 0,
+        shareToken: null,
+        sharedAt: null,
+        expiresAt: null,
+        createdAt: now,
+        updatedAt: now,
+    };
+}
+/**
+ * The draft's result page as a visitor (`member` false) or its owner gets it: its share targets,
+ * filled from the wizard's last finished test run, and what that run wrote. `resultId` picks the
+ * result step where the draft has several.
+ */
+export async function sharePreview(wizard, userId, resultId, member, lang) {
+    const last = await db.query.run.findFirst({
+        where: and(eq(schema.run.tenantId, currentTenant()), eq(schema.run.wizardId, wizard.id), eq(schema.run.mode, "test"), eq(schema.run.status, "done")),
+        orderBy: [desc(schema.run.createdAt)],
+    });
+    // The draft as it is now, on what the last test run answered and made.
+    const run = {
+        ...(last ?? standIn(wizard, userId)),
+        definition: wizard.draft,
+        cursor: resultId,
+    };
+    const scope = targetScope(run, wizard.projectId, lang);
+    const templates = await templateScope(run, wizard.projectId);
+    const { entries, listed, missing } = await namedTargets(run, wizard.projectId);
+    const targets = [];
+    const left = missing.map((name) => ({ name, why: "setup" }));
+    for (const entry of entries) {
+        const name = entry.label ?? sayIn(lang, entry.target.name);
+        if (!listed && entry.target.agent && !member) {
+            left.push({ name, why: "agent" });
+        }
+        else if (!(await offerable(entry.target, wizard.projectId))) {
+            left.push({ name, why: "setup" });
+        }
+        else {
+            targets.push({
+                ...(await targetView(entry, scope, templates)),
+                empty: emptyPlaceholders(entry.values, templates),
+            });
+        }
+    }
+    const outputs = {};
+    for (const d of resultStepOf(run)?.deliverables ?? []) {
+        const text = run.state.outputs[d.from]?.text?.trim();
+        if (text) {
+            outputs[d.from] = text.slice(0, EXCERPT);
+        }
+    }
+    return {
+        run: last ? { id: last.id, at: last.updatedAt.toISOString() } : null,
+        targets,
+        left,
+        outputs,
+    };
+}
+// The account a target sends with is a connection of its own, kept like the wizard's connections.
+registerConnectionSource(async (_run, connectionId, projectId) => {
+    if (!connectionId.startsWith("share:")) {
+        return null;
+    }
+    const target = await shareTarget(projectId, connectionId.slice("share:".length));
+    return target?.connection?.() ?? null;
+});

package/apps/runtime/dist/sharing/jobs.js

@@ -0,0 +1,186 @@
+import { noteText } from "@engenty/wizards-shared/run";
+import { connectionContext } from "../connectors/index.js";
+import { askPerson } from "../engine/asks.js";
+import { signalChanged } from "../engine/events.js";
+import { releaseResources } from "../engine/resources.js";
+import { loadProject, makeContext, projectIdOf } from "../engine/runner.js";
+import { env } from "../env.js";
+import { errorText } from "../model-errors.js";
+import { ServiceError } from "../services/errors.js";
+import { shareRun } from "../services/shares.js";
+import { scopeOf } from "../store/index.js";
+import { serverText } from "../texts.js";
+import { SHARE_STEP } from "./agent.js";
+import { shareFiles } from "./files.js";
+import { offeredTargets, targetScope } from "./index.js";
+import { addJobEvent, createJob, finishJob, jobCount, sentCount, setWorking, workingJob, } from "./state.js";
+import { parseRecipients } from "./targets/email.js";
+import { ShareError, sayIn } from "./types.js";
+/** What the person filled in does not do: per field, what is wrong. `_files` and `_account` name the other steps. */
+export class ShareInputError extends Error {
+    fields;
+    constructor(fields, said) {
+        super(Object.values(fields)[0] ?? said);
+        this.fields = fields;
+    }
+}
+/** Jobs one run of a person without an account may start. */
+const VISITOR_JOBS = 20;
+/** A link people elsewhere can open: not one that points at this machine. */
+function publicOrigin() {
+    const host = new URL(env.appUrl).hostname;
+    return !(host === "localhost" ||
+        host.endsWith(".localhost") ||
+        host.endsWith(".local") ||
+        host === "127.0.0.1" ||
+        host === "[::1]");
+}
+function contextOf(run, projectId, entry, who, job) {
+    const connection = entry.target.connection?.() ?? null;
+    const signal = job?.signal ?? new AbortController().signal;
+    const emit = (message) => job ? addJobEvent(run.id, job.id, sayIn(who.lang, message)) : Promise.resolve();
+    const ask = (question) => !job || run.unattended
+        ? Promise.resolve(null)
+        : askPerson(run.id, { ...question, stepId: SHARE_STEP }, signal);
+    return {
+        ...targetScope(run, projectId, who.lang),
+        signal,
+        member: who.member,
+        sentBefore: job?.sentBefore ?? 0,
+        emit,
+        ask,
+        account: () => connection ? connectionContext(scopeOf(run), connection, projectId) : Promise.resolve(null),
+        link: async () => (publicOrigin() ? (await shareRun(run)).url : null),
+        step: async () => makeContext(run, await loadProject(run), structuredClone(run.state), signal, {
+            stepId: SHARE_STEP,
+            emit: (_type, message) => emit(typeof message === "string" ? message : noteText(message, who.lang)),
+            ask,
+        }),
+    };
+}
+async function entryOf(run, projectId, key, member) {
+    const entry = (await offeredTargets(run, projectId, member)).find((e) => e.key === key);
+    if (!entry) {
+        throw new ServiceError("not_found", { server: "shareTargetUnknown" });
+    }
+    return entry;
+}
+/**
+ * Sends a finished result to one target. Answers as soon as the job stands; the work goes on in
+ * the background and shows in the run's view. One job per run at a time.
+ */
+export async function startShare(run, request, who) {
+    if (run.status !== "done") {
+        throw new ServiceError("refused", { server: "shareOnlyDone" });
+    }
+    if (workingJob(run.id)) {
+        throw new ServiceError("refused", { server: "shareBusy" });
+    }
+    // A run of someone without an account sends a limited number of times: it is no mail relay.
+    if (!who.member && (await jobCount(run.id)) >= VISITOR_JOBS) {
+        throw new ServiceError("refused", { server: "shareTooOften" });
+    }
+    const lang = request.lang ?? "en";
+    const projectId = await projectIdOf(run);
+    const entry = await entryOf(run, projectId, request.target, who.member);
+    const { target } = entry;
+    const values = {};
+    const errors = {};
+    for (const field of target.fields) {
+        const value = String(request.values[field.id] ?? "")
+            .trim()
+            .slice(0, field.kind === "textarea" ? 20_000 : 2000);
+        values[field.id] = value;
+        if (!value) {
+            if (field.required) {
+                errors[field.id] = serverText(lang, "shareRequired");
+            }
+            continue;
+        }
+        if (field.kind === "url" && !/^https?:\/\/[^\s/]+\.[^\s]+$/i.test(value)) {
+            errors[field.id] = serverText(lang, "shareNeedsHttps");
+        }
+        if (field.kind === "emails") {
+            try {
+                parseRecipients(value);
+            }
+            catch (err) {
+                errors[field.id] = errorText(err, lang);
+            }
+        }
+    }
+    const items = target.takes === "files" ? request.items.slice(0, 20) : [];
+    if (target.needsFiles && !items.length) {
+        errors._files = serverText(lang, "sharePickFile");
+    }
+    const connection = target.connection?.() ?? null;
+    if (connection && !(await connectionContext(scopeOf(run), connection, projectId))) {
+        errors._account = serverText(lang, "shareConnectAccount");
+    }
+    if (Object.keys(errors).length) {
+        throw new ShareInputError(errors, serverText(lang, "shareCheckInput"));
+    }
+    const job = await createJob({
+        runId: run.id,
+        target: target.id,
+        name: entry.label ?? sayIn(lang, target.name),
+        icon: target.icon,
+        request: { target: request.target, items, values, lang },
+    });
+    const abort = new AbortController();
+    setWorking(run.id, { jobId: job.id, abort });
+    const ctx = contextOf(run, projectId, entry, { member: who.member, lang }, { id: job.id, signal: abort.signal, sentBefore: await sentCount(run.id, target.id) });
+    void (async () => {
+        try {
+            if (items.length) {
+                await ctx.emit({ server: "sharePreparing" });
+            }
+            const files = await shareFiles(run, items);
+            const outcome = await target.send({ values, files }, ctx);
+            await finishJob(run.id, job.id, abort.signal.aborted
+                ? { status: "cancelled" }
+                : {
+                    status: "done",
+                    result: { summary: sayIn(lang, outcome.summary), url: outcome.url ?? null },
+                });
+        }
+        catch (err) {
+            if (!abort.signal.aborted && !(err instanceof ShareError)) {
+                console.error(`[share ${run.id} → ${target.id}]`, err);
+            }
+            await finishJob(run.id, job.id, abort.signal.aborted
+                ? { status: "cancelled" }
+                : {
+                    status: "failed",
+                    error: err instanceof ShareError
+                        ? errorText(err, lang)
+                        : `${serverText(lang, "shareFailed")}: ${String(err?.message ?? err).slice(0, 240)}`,
+                }).catch(() => undefined);
+        }
+        finally {
+            setWorking(run.id, null);
+            await releaseResources(run.id).catch(() => undefined);
+            signalChanged(run.id);
+        }
+    })();
+    return job;
+}
+/** Stops the job a run is working on; what it already sent stays sent. */
+export async function cancelShare(runId, jobId) {
+    const job = workingJob(runId);
+    if (!job || (jobId && job.jobId !== jobId)) {
+        return false;
+    }
+    job.abort.abort();
+    await finishJob(runId, job.jobId, { status: "cancelled" });
+    return true;
+}
+/** The choices of a form field that come from the connected account (Slack's channels). */
+export async function shareChoices(run, key, field, who) {
+    const projectId = await projectIdOf(run);
+    const entry = await entryOf(run, projectId, key, who.member);
+    if (!entry.target.choices) {
+        return [];
+    }
+    return entry.target.choices(field, contextOf(run, projectId, entry, who, null));
+}

package/apps/runtime/dist/sharing/state.js

@@ -0,0 +1,116 @@
+import { and, desc, eq } from "drizzle-orm";
+import { nanoid } from "nanoid";
+import { db, schema } from "../db/client.js";
+import { pendingAsk } from "../engine/asks.js";
+import { signalChanged } from "../engine/events.js";
+import { currentTenant } from "../tenants/tenant.js";
+import { serverText } from "../texts.js";
+/** Jobs this process is working on, by run. One at a time per run: they share its browser. */
+const working = new Map();
+export function workingJob(runId) {
+    return working.get(runId) ?? null;
+}
+export function setWorking(runId, job) {
+    if (job) {
+        working.set(runId, job);
+    }
+    else {
+        working.delete(runId);
+    }
+}
+async function view(row) {
+    return {
+        id: row.id,
+        target: row.target,
+        name: row.name,
+        icon: row.icon,
+        status: row.status,
+        events: row.events,
+        ask: row.status === "running" ? await pendingAsk(row.runId) : null,
+        result: row.result ?? null,
+        error: row.error,
+        createdAt: row.createdAt.toISOString(),
+    };
+}
+/** A job left "running" by a server that stopped: nobody works on it any more. */
+async function settled(row) {
+    if (row.status !== "running" || working.get(row.runId)?.jobId === row.id) {
+        return row;
+    }
+    const error = serverText(row.request.lang ?? "en", "shareInterrupted");
+    await db
+        .update(schema.shareJob)
+        .set({ status: "failed", error, updatedAt: new Date() })
+        .where(eq(schema.shareJob.id, row.id));
+    return { ...row, status: "failed", error };
+}
+export async function createJob(input) {
+    const [row] = await db
+        .insert(schema.shareJob)
+        // The column's default counts whole seconds; jobs of one second must still keep their order.
+        .values({
+        id: nanoid(14),
+        tenantId: currentTenant(),
+        status: "running",
+        createdAt: new Date(),
+        ...input,
+    })
+        .returning();
+    signalChanged(input.runId);
+    return view(row);
+}
+export async function addJobEvent(runId, jobId, message) {
+    const row = await db.query.shareJob.findFirst({ where: eq(schema.shareJob.id, jobId) });
+    if (!row) {
+        return;
+    }
+    const events = [
+        ...row.events,
+        { at: new Date().toISOString(), message: message.slice(0, 300) },
+    ].slice(-40);
+    await db
+        .update(schema.shareJob)
+        .set({ events, updatedAt: new Date() })
+        .where(eq(schema.shareJob.id, jobId));
+    signalChanged(runId);
+}
+export async function finishJob(runId, jobId, end) {
+    await db
+        .update(schema.shareJob)
+        .set({
+        status: end.status,
+        result: end.status === "done" ? end.result : null,
+        error: end.status === "failed" ? end.error : null,
+        updatedAt: new Date(),
+    })
+        .where(and(eq(schema.shareJob.id, jobId), eq(schema.shareJob.status, "running")));
+    signalChanged(runId);
+}
+export async function shareJobs(runId, limit = 12) {
+    const rows = await db.query.shareJob.findMany({
+        where: eq(schema.shareJob.runId, runId),
+        orderBy: [desc(schema.shareJob.createdAt), desc(schema.shareJob.id)],
+        limit,
+    });
+    return Promise.all(rows.map(async (row) => view(await settled(row))));
+}
+/** The run's newest job: the one on its way, or the last one that arrived or failed. */
+export async function latestShareJob(runId) {
+    return (await shareJobs(runId, 1))[0] ?? null;
+}
+/** How many jobs a run has started, whatever became of them. */
+export async function jobCount(runId) {
+    const rows = await db.query.shareJob.findMany({
+        where: eq(schema.shareJob.runId, runId),
+        columns: { id: true },
+    });
+    return rows.length;
+}
+/** How often a target has sent for a run. */
+export async function sentCount(runId, target) {
+    const rows = await db.query.shareJob.findMany({
+        where: and(eq(schema.shareJob.runId, runId), eq(schema.shareJob.target, target), eq(schema.shareJob.status, "done")),
+        columns: { id: true },
+    });
+    return rows.length;
+}