@superpanel-sdk/runtime 0.2.3 → 0.7.0

package/dist/cli/mobile/index.js

@@ -0,0 +1,405 @@
+/**
+ * `superpanel-sdk-runtime mobile` (68 §5.4): a test customer's phone in the terminal. This repository's code
+ * serves the environment (as `connect()` does); you are the customer: call a line and talk in text, text it,
+ * email it, and get what the environment sends you on its own (its texts, its emails, its calls ringing),
+ * answered or let ring. Plain lines are what you say on the call you are on, else a text to the line.
+ * Commands start with `/` (`/help`). Lines piped in run one after another, so a script or an agent can
+ * drive it: `printf '/call\nHi, this is Carl\n/hangup\n' | npm run mobile`.
+ */
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { createInterface } from 'node:readline';
+import { connect } from '../../testing.js';
+import { formatTurnLine } from '../turns/index.js';
+const HELP = `What you type:
+  <text>                    say it on the call you are on; else text it to the line
+  /call [line]              call a line (the line you text when left out)
+  /sms <text>               text the line, on a call or not
+  /burst <a> | <b> | …      several texts in a row, batched as a carrier's are (one run after 15 s quiet)
+  /email <subject> | <body> email the mailbox (a new thread)
+  /reply <body>             answer the last email you got, in its thread
+  /answer [voicemail|screening|ivr]   pick up the call ringing you (a person when left out)
+  /decline [busy]           let it ring (no-answer), or be busy
+  /press <keys>             press keys for the keypad the call asked for
+  /transfer answered|failed the transfer the call asked for: taken, or not
+  /hangup                   hang up
+  /wait sms|email|call [s]  wait for the environment to send you one (60 s when left out)
+  /due                      do your case's next scheduled step now (a call or text booked for a later day)
+  /inbox                    everything sent to you since you started
+  /turns                    your case's turns: what was heard, said, pressed and written
+  /line <name>, /mailbox <name>   where calls, texts and emails go
+  /whoami                   your number, address, line, mailbox and case
+  /help, /quit`;
+const tty = process.stdout.isTTY === true;
+const paint = (code) => (text) => (tty ? `\x1b[${code}m${text}\x1b[0m` : text);
+const ai = paint('36');
+const dim = paint('2');
+const alert = paint('33');
+const bad = paint('31');
+/** The test customer this repository last used for an environment, kept in .superpanel/mobile/. */
+function identity(repoRoot, environmentId, fresh, make) {
+    const file = path.join(repoRoot, '.superpanel', 'mobile', `${environmentId}.json`);
+    if (!fresh) {
+        try {
+            const kept = JSON.parse(readFileSync(file, 'utf8'));
+            if (typeof kept.phone === 'string' && typeof kept.email === 'string')
+                return { phone: kept.phone, email: kept.email };
+        }
+        catch {
+            // none yet
+        }
+    }
+    const made = make();
+    mkdirSync(path.dirname(file), { recursive: true });
+    writeFileSync(file, `${JSON.stringify(made, null, 2)}\n`);
+    return made;
+}
+export async function runMobile(repoRoot, options) {
+    const out = (line) => print(line);
+    out(dim(`connecting to ${options.env ?? 'sandbox'}: this repository's code serves it while the phone is on…`));
+    const sandbox = await connect({ env: options.env ?? 'sandbox', repoRoot, ...(options.url ? { url: options.url } : {}) });
+    const probe = sandbox.sim.customer();
+    const me = identity(repoRoot, sandbox.environment.id, options.new === true, () => ({ phone: probe.phone, email: probe.email }));
+    const customer = sandbox.sim.customer(me);
+    const state = {
+        line: options.line ?? 'Main line',
+        mailbox: options.mailbox ?? 'Support',
+        call: null,
+        ringing: [],
+        lastEmail: null,
+        /** Your cases, the latest last: your number and your address may be different contacts, each with its own. */
+        cases: [],
+    };
+    const since = new Date(Date.now() - 1_000).toISOString();
+    const seen = new Set();
+    const arrived = [];
+    const waiters = [];
+    // ── Output while you type ──────────────────────────────────────────────────────────────────────
+    const rl = createInterface({ input: process.stdin, output: process.stdout, terminal: tty });
+    rl.setPrompt(tty ? '📱 ' : '');
+    function print(line) {
+        if (tty)
+            process.stdout.write('\r\x1b[K');
+        process.stdout.write(`${line}\n`);
+        if (tty && rl)
+            rl.prompt(true);
+    }
+    const showItem = (item) => {
+        if (item.kind === 'sms')
+            out(`${alert('💬 text')} from ${item.line ?? item.from}: ${item.body}`);
+        if (item.kind === 'email') {
+            out(`${alert('✉  email')} from ${item.mailbox ?? item.from}: ${item.subject}`);
+            for (const line of item.body.split('\n'))
+                out(`   ${line}`);
+            out(dim('   (/reply <body> to answer)'));
+        }
+        if (item.kind === 'call')
+            out(`${alert('📞 ringing')} from ${item.line ?? item.from} ${dim('(/answer or /decline)')}`);
+    };
+    const take = (item, show) => {
+        if (seen.has(item.id))
+            return;
+        seen.add(item.id);
+        if (item.kind === 'call')
+            state.ringing.push(item);
+        if (item.kind === 'email')
+            state.lastEmail = item;
+        if (show)
+            showItem(item);
+        const waiter = waiters.findIndex((w) => w.kind === item.kind);
+        if (waiter >= 0)
+            waiters.splice(waiter, 1)[0].resolve(item);
+        else
+            arrived.push(item);
+    };
+    const showTurns = (turns) => {
+        for (const turn of turns) {
+            if (turn.instanceId)
+                state.cases = [...state.cases.filter((id) => id !== turn.instanceId), turn.instanceId];
+            for (const thought of turn.thoughts ?? [])
+                out(dim(`   (thought) ${thought}`));
+            for (const action of turn.actions)
+                out(dim(`   ${action.key}: ${action.status}${action.error ? ` (${action.error})` : ''}`));
+            for (const write of turn.writes)
+                out(dim(`   wrote ${write.table}.${write.field} = ${JSON.stringify(write.value)}${write.state && write.state !== 'filled' ? ` (${write.state})` : ''}`));
+            if (turn.error)
+                out(bad(`   ${turn.error}`));
+        }
+    };
+    const showOrchestrator = (orchestrator) => {
+        if (!orchestrator)
+            return;
+        const booked = orchestrator.scheduled.map((a) => {
+            const action = a;
+            return `${action.kind ?? 'step'} at ${action.scheduledFor ?? '?'}${action.reason ? ` (${action.reason})` : ''}`;
+        });
+        out(dim(`   Orchestrator: ${orchestrator.status}${booked.length ? `; booked ${booked.join('; ')}` : ''}${orchestrator.cancelled.length ? `; cancelled ${orchestrator.cancelled.length}` : ''}`));
+    };
+    const showStep = (step) => {
+        for (const said of step.said)
+            out(`${ai('AI:')} ${said}`);
+        for (const event of step.events) {
+            if (event.kind === 'keypad')
+                out(alert(`   ⌨  keypad ${event.key}: "${event.say}" (${event.digits.join(', ')}) — /press <keys>`));
+            else if (event.kind === 'transfer')
+                out(alert(`   ↪  transfer to ${event.to} (${event.mode}) — /transfer answered|failed`));
+            else if (event.kind === 'voicemail')
+                out(alert(`   📼 voicemail left: "${event.text}"`));
+            else if (event.kind === 'language')
+                out(dim(`   language: ${event.language}`));
+            else if (event.kind === 'far_end')
+                out(dim(`   who answered (${event.farEnd}): ${event.decision}`));
+        }
+        showTurns(step.turns);
+        if (step.ended) {
+            out(alert(`📴 call ended (${step.ended.by})`));
+            showOrchestrator(step.ended.orchestrator);
+            state.call = null;
+        }
+    };
+    const showSent = (result) => {
+        showTurns(result.turns);
+        for (const reply of result.replies)
+            take(reply, true);
+        if (!result.replies.length)
+            out(dim('   (no reply)'));
+        showOrchestrator(result.orchestrator);
+    };
+    // ── What the environment sends you, as it comes ────────────────────────────────────────────────
+    let polling = true;
+    const poll = async () => {
+        while (polling) {
+            try {
+                for (const item of await customer.inbox(since))
+                    take(item, true);
+                // A call that stopped ringing (answered elsewhere, or ended) is no longer to answer.
+                const ringingNow = new Set((await customer.inbox(since)).filter((i) => i.kind === 'call').map((i) => i.id));
+                state.ringing = state.ringing.filter((c) => ringingNow.has(c.id));
+            }
+            catch (error) {
+                out(bad(`inbox: ${error instanceof Error ? error.message : String(error)}`));
+            }
+            await new Promise((resolve) => setTimeout(resolve, 2_000));
+        }
+    };
+    const waitFor = (kind, seconds) => new Promise((resolve) => {
+        const ready = arrived.findIndex((item) => item.kind === kind);
+        if (ready >= 0)
+            return resolve(arrived.splice(ready, 1)[0]);
+        const waiter = { kind, resolve: (item) => (clearTimeout(timer), resolve(item)) };
+        const timer = setTimeout(() => {
+            waiters.splice(waiters.indexOf(waiter), 1);
+            resolve(null);
+        }, seconds * 1_000);
+        waiters.push(waiter);
+    });
+    /** Your open cases, the latest first: the ones you talked on here, else the ones your number and address have. */
+    const caseIds = async () => {
+        if (!state.cases.length) {
+            for (const lookup of [{ phone: me.phone }, { email: me.email }]) {
+                const { contacts } = await sandbox.ctx.api.contact.find(lookup);
+                for (const contact of contacts) {
+                    const { instances } = await sandbox.ctx.api.instances.findForContact({ contactId: contact.id, activeOnly: true });
+                    for (const instance of instances)
+                        if (!state.cases.includes(instance.id))
+                            state.cases.push(instance.id);
+                }
+            }
+        }
+        return [...state.cases].reverse();
+    };
+    const onCall = () => {
+        if (!state.call)
+            throw new Error('you are not on a call: /call, or /answer one ringing you');
+        return state.call;
+    };
+    const ringingCall = () => {
+        const call = state.ringing.shift();
+        if (!call)
+            throw new Error('nothing is ringing you (/wait call waits for one)');
+        return call;
+    };
+    // ── What you type ─────────────────────────────────────────────────────────────────────────────
+    const commands = {
+        help: async () => out(HELP),
+        whoami: async () => out(`you: ${me.phone}, ${me.email}\nline: ${state.line}; mailbox: ${state.mailbox}\nenvironment: ${sandbox.environment.name}${state.cases.length ? `\ncases: ${state.cases.join(', ')}` : ''}`),
+        line: async (rest) => {
+            if (!rest)
+                throw new Error('/line <name>');
+            state.line = rest;
+            const line = await sandbox.sim.line(rest);
+            out(dim(`line ${line.name}: ${line.number}`));
+        },
+        mailbox: async (rest) => {
+            if (!rest)
+                throw new Error('/mailbox <name>');
+            state.mailbox = rest;
+            const box = await sandbox.sim.mailbox(rest);
+            out(dim(`mailbox ${box.name}: ${box.address}`));
+        },
+        call: async (rest) => {
+            if (state.call)
+                throw new Error('you are on a call: /hangup first');
+            if (rest)
+                state.line = rest;
+            await sandbox.sim.line(state.line);
+            out(dim(`calling ${state.line}…`));
+            const call = await sandbox.call.inbound({ from: me.phone, to: state.line });
+            state.call = call;
+            showStep(call.opening);
+        },
+        sms: async (rest) => {
+            if (!rest)
+                throw new Error('/sms <text>');
+            await sandbox.sim.line(state.line);
+            showSent(await customer.text(rest, { to: state.line, orchestrator: 'now' }));
+        },
+        burst: async (rest) => {
+            const texts = rest.split('|').map((part) => part.trim()).filter(Boolean);
+            if (texts.length < 2)
+                throw new Error('/burst <text> | <text> | …');
+            await sandbox.sim.line(state.line);
+            for (const body of texts)
+                await customer.text(body, { to: state.line, debounce: 'real' });
+            out(dim(`${texts.length} texts sent; the line answers once they stop coming (about 15 s)…`));
+            if (!(await waitFor('sms', 90)))
+                throw new Error('no reply came within 90 s');
+        },
+        email: async (rest) => {
+            const [subject, ...body] = rest.split('|');
+            if (!subject?.trim() || !body.join('|').trim())
+                throw new Error('/email <subject> | <body>');
+            await sandbox.sim.mailbox(state.mailbox);
+            showSent(await customer.sendEmail({ to: state.mailbox, subject: subject.trim(), body: body.join('|').trim(), orchestrator: 'now' }));
+        },
+        reply: async (rest) => {
+            const last = state.lastEmail;
+            if (!last)
+                throw new Error('no email to answer yet: /email starts a thread');
+            if (!rest)
+                throw new Error('/reply <body>');
+            const subject = /^re:/i.test(last.subject) ? last.subject : `Re: ${last.subject}`;
+            showSent(await customer.sendEmail({ to: last.from, subject, body: rest, threadId: last.threadId, orchestrator: 'now' }));
+        },
+        answer: async (rest) => {
+            if (state.call)
+                throw new Error('you are on a call: /hangup first');
+            const as = (rest || 'human');
+            if (!['human', 'voicemail', 'screening', 'ivr'].includes(as))
+                throw new Error('/answer [voicemail|screening|ivr]');
+            const call = await customer.answer(ringingCall(), { as, orchestrator: 'now' });
+            state.call = call.ended ? null : call;
+            showStep(call.opening);
+        },
+        decline: async (rest) => {
+            const status = rest === 'busy' ? 'busy' : 'no-answer';
+            showStep(await customer.decline(ringingCall(), { status, orchestrator: 'now' }));
+        },
+        press: async (rest) => {
+            if (!rest)
+                throw new Error('/press <keys>');
+            showStep(await onCall().press(rest));
+        },
+        transfer: async (rest) => {
+            if (rest !== 'answered' && rest !== 'failed')
+                throw new Error('/transfer answered|failed');
+            showStep(await onCall().transfer(rest));
+        },
+        hangup: async () => showStep(await onCall().hangup()),
+        wait: async (rest) => {
+            const [kind, seconds] = rest.split(/\s+/);
+            if (kind !== 'sms' && kind !== 'email' && kind !== 'call')
+                throw new Error('/wait sms|email|call [seconds]');
+            const wait = Number(seconds) > 0 ? Number(seconds) : 60;
+            out(dim(`waiting up to ${wait} s for ${kind === 'sms' ? 'a text' : kind === 'call' ? 'a call' : 'an email'}…`));
+            if (!(await waitFor(kind, wait)))
+                throw new Error(`no ${kind} came within ${wait} s`);
+        },
+        due: async () => {
+            const cases = await caseIds();
+            if (!cases.length)
+                throw new Error('you have no open case yet: call, text or email first');
+            // The latest case with something scheduled: its earliest step.
+            for (const instanceId of cases) {
+                const due = await sandbox.runDue({ instanceId });
+                if (!due.action)
+                    continue;
+                out(dim(`done now: ${due.action.kind}${due.action.reason ? ` (${due.action.reason})` : ''}, booked for ${due.action.scheduledFor}`));
+                return;
+            }
+            out(dim('nothing scheduled on your cases'));
+        },
+        inbox: async () => {
+            const items = await customer.inbox(since);
+            if (!items.length)
+                out(dim('nothing yet'));
+            for (const item of items)
+                showItem(item);
+        },
+        turns: async () => {
+            const cases = await caseIds();
+            if (!cases.length)
+                throw new Error('you have no case yet');
+            for (const instanceId of [...cases].reverse()) {
+                out(dim(`case ${instanceId}`));
+                for (const turn of await sandbox.turns({ instanceId }))
+                    out(formatTurnLine(turn));
+            }
+        },
+    };
+    out(`📱 ${me.phone} · ${me.email} on ${sandbox.environment.name} — /help for what you can do`);
+    void poll();
+    if (tty)
+        rl.prompt();
+    let quitting = false;
+    for await (const raw of rl) {
+        const line = raw.trim();
+        if (!line) {
+            if (tty)
+                rl.prompt();
+            continue;
+        }
+        if (!tty)
+            out(dim(`> ${line}`));
+        try {
+            if (line.startsWith('/')) {
+                const [name = '', ...rest] = line.slice(1).split(' ');
+                if (name === 'quit' || name === 'exit') {
+                    quitting = true;
+                    break;
+                }
+                const command = commands[name];
+                if (!command)
+                    throw new Error(`/${name}: no such command (/help)`);
+                await command(rest.join(' ').trim());
+            }
+            else if (state.call) {
+                showStep(await state.call.say(line));
+            }
+            else {
+                await commands.sms(line);
+            }
+        }
+        catch (error) {
+            out(bad(error instanceof Error ? error.message : String(error)));
+        }
+        if (tty)
+            rl.prompt();
+    }
+    // Leave nothing open: the call you are on is hung up, so its case moves on.
+    if (state.call) {
+        try {
+            showStep(await state.call.hangup());
+        }
+        catch {
+            // ended meanwhile
+        }
+    }
+    polling = false;
+    rl.close();
+    await sandbox.close();
+    if (!quitting && !tty)
+        out(dim('input ended'));
+    process.exit(0);
+}
+//# sourceMappingURL=index.js.map

package/dist/cli/serve/index.d.ts

@@ -1,9 +1,115 @@
+import type { AnyEventHandlers } from '../../core/functions/events.js';
+import type { FuncMap } from '../../core/functions/types.js';
+import { type CompanyPart, type RuntimePackageSource, type SequenceBuild, type SourceMaps } from '../../builder/types.js';
+import { type OverlayAuthErrorMessage } from '../../dev-overlay/protocol.js';
 export type ServeOptions = {
     url?: string;
-    apiKey?: string;
-    companyId?: string;
-    sequenceIds?: string[];
+    environment?: string;
+    openBrowser?: boolean;
+};
+type LoadedSequence = {
+    build: SequenceBuild;
+    /** Its code's maps by `functionKey` (the page script's: the backend runs the page this compiled). */
+    sourceMaps: SourceMaps;
+    functions: FuncMap;
+    events: AnyEventHandlers;
+    generation: number;
+};
+/** The company-level functions (22 §5), compiled without code, and their implementations. */
+type LoadedCompany = {
+    /** Its `schema` comes from `schema/`, apart from any sequence: a repository with no sequence still pushes it. */
+    part: CompanyPart;
+    functions: FuncMap;
+};
+/** What one execute runs on: a sequence's functions, or the company's. */
+type Executable = {
+    functions: FuncMap;
+    events: AnyEventHandlers;
+    runtimeVersion: string;
+    runtimeSource: RuntimePackageSource;
 };
 export declare function overlayWebSocketUrl(raw: string): string;
+/** Not the repository's code: dependencies, git, and what compiling writes. */
+export declare function isIgnoredServePath(repoRoot: string, file: string): boolean;
+/**
+ * What a changed file recompiles (22-sequence-as-business-unit §6): a file of one sequence, that
+ * sequence; anything else (`schema/`, `resolve.ts`, shared code) can reach every sequence, so all.
+ */
+export declare function reloadScopeForPath(repoRoot: string, file: string): 'all' | {
+    sequenceId: string;
+} | null;
+export declare function loadCompany(repoRoot: string): Promise<LoadedCompany>;
+/** What a reload recompiles: the whole repository, or these sequences. */
+export type ReloadJob = {
+    all: boolean;
+    ids: Set<string>;
+};
+/**
+ * The changes waiting to be reloaded. A reload that fails keeps its scope (`fail`) for the next one,
+ * which a new file change starts (no retry on its own: the failure is in the code until it is
+ * edited); it is cleared only once a reload of it loads.
+ */
+export declare class ReloadQueue {
+    private pending;
+    private failed;
+    add(scope: 'all' | {
+        sequenceId: string;
+    }): void;
+    /** Something changed since the last reload. */
+    hasChanges(): boolean;
+    /** The next reload: the new changes plus what failed before. */
+    take(): ReloadJob;
+    fail(job: ReloadJob): void;
+}
+/** What a serve runs and pushes: the company's code and every loaded sequence. */
+export type ServeState = {
+    company: LoadedCompany;
+    sequences: Map<string, LoadedSequence>;
+};
+/**
+ * The state after a reload (`all`: the whole repository; else the sequences `ids` names), built
+ * aside: if any part fails to load it throws and the current state stays whole, never new company
+ * code with old sequences.
+ */
+export declare function reloadServeState(repoRoot: string, current: ServeState, job: {
+    all: boolean;
+    ids: Iterable<string>;
+}, generation: number): Promise<ServeState>;
+/**
+ * Push the local company build: the company's functions and every loaded sequence, as one overlay.
+ * With no sequence left it is still pushed, so the environment drops the ones it had (22 §11).
+ */
+export declare function pushOverlay(ws: Pick<WebSocket, 'send'>, company: LoadedCompany, sequences: Map<string, LoadedSequence>, generation: number): void;
+/**
+ * What the company is shown of a failed function's stack (the backend's company logs): the error's first
+ * line and the frames of the repository's own files, by their path from its root. tsx runs the original
+ * files, so their lines are already the company's. Undefined when no frame is the repository's.
+ */
+export declare function repositoryStack(error: unknown, repoRoot: string): string | undefined;
+export declare function toOverlayError(message: OverlayAuthErrorMessage): Error;
+/**
+ * Runs each `execute` the backend sends, unless its deadline has passed: the backend has then reported
+ * it as failed (a paused process, a laptop that slept), and running it would repeat its effects when
+ * the call is retried. One already started is not interrupted.
+ */
+export declare function attachExecuteHandler(ws: Pick<WebSocket, 'addEventListener' | 'send'>, find: (scope: string) => Executable | undefined, rpcUrl: string, repoRoot: string): void;
 export declare function runServe(repoRoot: string, options?: ServeOptions): Promise<void>;
+/** A Local Serve opened from code (the integration tests' `connect`): the repository's code on one environment until `close`. */
+export type OpenOverlay = {
+    /** Stops serving: the environment runs its release again. */
+    close(): Promise<void>;
+    /** The sequences served. */
+    sequences: string[];
+};
+/**
+ * The repository served on `environmentId` as `serve` serves it, once (no file watch, no reconnect): its
+ * code loaded through the company import graph (an import the compile refuses fails here), pushed, and
+ * every function the environment runs meanwhile run here. Resolves once the environment took it.
+ */
+export declare function openOverlay(repoRoot: string, options: {
+    backendUrl: string;
+    token: string;
+    environmentId: string;
+}): Promise<OpenOverlay>;
+export {};
 //# sourceMappingURL=index.d.ts.map