@superpanel-sdk/runtime 0.2.3 → 0.7.0

package/dist/cli/exec/index.js

@@ -0,0 +1,138 @@
+/**
+ * `exec <file>`: the repository's integration test. A code snippet runs on this machine, and every
+ * `ctx.api` call it makes reaches one environment's real data, through the same RPC and checks as a
+ * function the platform runs (the backend's `exec/exec-run.ts` scopes its run token: this company, one
+ * non-prod environment, optionally one case). What it writes is written.
+ *
+ * The snippet is a `.ts` file whose default export is `(ctx, args) => value`. To try a sequence's
+ * function on real data, the snippet imports it and calls it with `ctx`. While it runs, this repository
+ * serves the environment (as `serve` does): local code and schema, the environment's data.
+ *
+ * Everything a run did is kept under `.superpanel/exec/<time>-<name>/`, for a person or an agent to read
+ * after: `result.json` (the value returned or the error, with the environment and the case), `calls.jsonl`
+ * (each `ctx.api` call: its arguments, its answer or error, how long it took) and `log.jsonl` (the
+ * snippet's `console` and `ctx.api.log` lines).
+ */
+import { appendFileSync, existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { openOverlay } from '../serve/index.js';
+import { openExecSession } from './session.js';
+import { traceApi } from './trace.js';
+export { traceApi };
+const LOG_METHODS = new Set(['debug', 'info', 'warn', 'error']);
+/** `YYYYMMDD-HHMMSS` of `date`, local time: the run's directory sorts by when it ran. */
+function stamp(date) {
+    const pad = (n) => String(n).padStart(2, '0');
+    return `${date.getFullYear()}${pad(date.getMonth() + 1)}${pad(date.getDate())}-${pad(date.getHours())}${pad(date.getMinutes())}${pad(date.getSeconds())}`;
+}
+/** A value as JSON for the files: what JSON cannot hold (a function, a cycle, a BigInt) as text. */
+function jsonLine(value) {
+    const seen = new WeakSet();
+    return JSON.stringify(value, (_key, v) => {
+        if (typeof v === 'bigint')
+            return `${v}n`;
+        if (typeof v === 'function')
+            return `[function ${v.name || 'anonymous'}]`;
+        if (v && typeof v === 'object') {
+            if (seen.has(v))
+                return '[cycle]';
+            seen.add(v);
+        }
+        return v;
+    });
+}
+/** A backend error that has a known fix, with the fix said. */
+function explain(message) {
+    if (/No overlay or published company build/.test(message)) {
+        return `${message}: this repository's code did not reach the environment; run again`;
+    }
+    return message;
+}
+export async function runExec(repoRoot, file, options = {}) {
+    const source = path.resolve(file);
+    if (!existsSync(source))
+        throw new Error(`${file}: no such file`);
+    let args = undefined;
+    if (options.args !== undefined) {
+        try {
+            args = JSON.parse(options.args);
+        }
+        catch {
+            throw new Error('--args is JSON, e.g. --args \'{"contact":"…"}\'');
+        }
+    }
+    const startedAt = new Date();
+    const name = path.basename(source).replace(/\.[cm]?tsx?$/, '');
+    const dir = path.join(repoRoot, '.superpanel', 'exec', `${stamp(startedAt)}-${name}`);
+    mkdirSync(dir, { recursive: true });
+    const callsFile = path.join(dir, 'calls.jsonl');
+    const logFile = path.join(dir, 'log.jsonl');
+    writeFileSync(callsFile, '');
+    writeFileSync(logFile, '');
+    const calls = { total: 0, failed: 0 };
+    const say = (line) => {
+        if (!options.json)
+            process.stderr.write(`${line}\n`);
+    };
+    const log = (level, source, message) => {
+        appendFileSync(logFile, `${jsonLine({ at: new Date().toISOString(), level, source, message: message.length === 1 ? message[0] : message })}\n`);
+    };
+    const record = (call) => {
+        calls.total += 1;
+        if (!call.ok)
+            calls.failed += 1;
+        appendFileSync(callsFile, `${jsonLine(call)}\n`);
+        const [surface, method] = call.call.split('.');
+        if (surface === 'log' && method && LOG_METHODS.has(method))
+            log(method, 'ctx.api.log', Array.isArray(call.input) ? call.input : [call.input]);
+        else
+            say(`  ${call.ok ? '·' : '✗'} ${call.call} ${call.ms}ms${call.ok ? '' : `: ${call.error}`}`);
+    };
+    const session = await openExecSession(repoRoot, { env: options.env, instance: options.instance, url: options.url, record });
+    const { run, ctx: traced } = session;
+    say(`exec ${path.relative(repoRoot, source)} in ${run.environment.name}${run.instance ? ` on ${run.instance.sequence} case ${run.instance.id}` : ''}`);
+    // This repository's code and schema serve the environment while the snippet runs: local code, the environment's data.
+    const overlay = await openOverlay(repoRoot, { backendUrl: session.backendUrl, token: session.loginToken, environmentId: run.environment.id });
+    say(`serving ${overlay.sequences.join(', ')} from this repository`);
+    // The snippet's console: kept in log.jsonl, and shown as usual unless --json.
+    const original = { ...console };
+    for (const level of ['log', 'info', 'warn', 'error', 'debug']) {
+        console[level] = (...message) => {
+            log(level === 'log' ? 'info' : level, 'console', message);
+            if (!options.json)
+                original[level](...message);
+        };
+    }
+    let result;
+    try {
+        const { tsImport } = await import('tsx/esm/api');
+        const mod = (await tsImport(pathToFileURL(source).href, import.meta.url));
+        if (typeof mod.default !== 'function') {
+            throw new Error(`${path.relative(repoRoot, source)}: the default export is the snippet, (ctx, args) => value`);
+        }
+        const value = await mod.default(traced, args);
+        result = { ok: true, file: path.relative(repoRoot, source), environment: run.environment, instance: run.instance, startedAt: startedAt.toISOString(), durationMs: Date.now() - startedAt.getTime(), calls, value, dir: path.relative(repoRoot, dir) };
+    }
+    catch (error) {
+        const err = error instanceof Error ? { message: explain(error.message), ...(error.stack ? { stack: error.stack } : {}) } : { message: String(error) };
+        result = { ok: false, file: path.relative(repoRoot, source), environment: run.environment, instance: run.instance, startedAt: startedAt.toISOString(), durationMs: Date.now() - startedAt.getTime(), calls, error: err, dir: path.relative(repoRoot, dir) };
+    }
+    finally {
+        Object.assign(console, original);
+        session.close();
+        await overlay.close();
+    }
+    writeFileSync(path.join(dir, 'result.json'), `${JSON.stringify(JSON.parse(jsonLine(result)), null, 2)}\n`);
+    if (options.json) {
+        process.stdout.write(`${jsonLine(result)}\n`);
+    }
+    else {
+        say(result.ok ? `ok in ${result.durationMs}ms, ${calls.total} ctx.api calls${calls.failed ? ` (${calls.failed} failed)` : ''}` : `failed: ${result.error.message}`);
+        if (result.ok && result.value !== undefined)
+            process.stdout.write(`${JSON.stringify(JSON.parse(jsonLine(result.value)), null, 2)}\n`);
+        say(`files: ${result.dir}/ (result.json, calls.jsonl, log.jsonl)`);
+    }
+    return result;
+}
+//# sourceMappingURL=index.js.map

package/dist/cli/exec/session.d.ts

@@ -0,0 +1,48 @@
+import type { SystemContext } from '../../core/context/types.js';
+import type { ActionDataSlice } from '../../fn-context/types.js';
+import { type ApiCall } from './trace.js';
+export type ExecRun = {
+    environment: {
+        id: string;
+        name: string;
+    };
+    instance: {
+        id: string;
+        sequence: string;
+    } | null;
+    runToken: string;
+    data: ActionDataSlice;
+};
+export type ExecSession = {
+    repoRoot: string;
+    backendUrl: string;
+    /** The CLI's login (serve token): what opens a Local Serve on the environment. */
+    loginToken: string;
+    run: ExecRun;
+    /** The real `ctx`: its `ctx.api` calls reach the environment, each one recorded. */
+    ctx: SystemContext;
+    /**
+     * The run token, renewed before it expires (it lasts 15 minutes: a long test file or an open `mobile`
+     * outlives it); `force` renews it now (a request that was refused). `run.runToken` is the current one.
+     */
+    token(force?: boolean): Promise<string>;
+    /** Stops renewing the token. */
+    close(): void;
+};
+/** A run token older than this is renewed before it is used; it expires at 15 minutes. */
+export declare const EXEC_TOKEN_RENEW_MS: number;
+/**
+ * A token renewed by `renew` once it is older than {@link EXEC_TOKEN_RENEW_MS}, or when `force`d; calls
+ * made while one renewal is under way share it.
+ */
+export declare function renewingToken(initial: string, renew: () => Promise<string>, now?: () => number): (force?: boolean) => Promise<string>;
+export declare function rpcUrlOf(backendUrl: string): string;
+/** Asks the backend for the run: its token, scope and `ctx` data. */
+export declare function requestExecRun(backendUrl: string, token: string, env: string, instance: string | undefined): Promise<ExecRun>;
+export declare function openExecSession(repoRoot: string, options: {
+    env?: string;
+    instance?: string;
+    url?: string;
+    record: (call: ApiCall) => void;
+}): Promise<ExecSession>;
+//# sourceMappingURL=session.d.ts.map

package/dist/cli/exec/session.js

@@ -0,0 +1,82 @@
+/**
+ * One exec session: the CLI's login traded for a run token on one environment (the backend's
+ * `exec/exec-run.ts`), and a real `ctx` built with it, every `ctx.api` call recorded. `exec <file>` runs
+ * a snippet in one; the integration tests' `connect()` keeps one open for a test file.
+ */
+import { runtimePackageSource, runtimePackageVersion } from '../../builder/compile/compile-sequence.js';
+import { buildActionContext } from '../../fn-context/build-context.js';
+import { createRpcApiHost } from '../../fn-context/rpc/trpc-client.js';
+import { setRuntimeLogLevel } from '../../logger.js';
+import { loadCachedServeAuthorization, resolveBackendUrl } from '../auth/auth.js';
+import { toHttpUrl } from '../auth/backend-url.js';
+import { apiUrl, requestJson } from '../auth/http.js';
+import { traceApi } from './trace.js';
+/** A run token older than this is renewed before it is used; it expires at 15 minutes. */
+export const EXEC_TOKEN_RENEW_MS = 10 * 60_000;
+/**
+ * A token renewed by `renew` once it is older than {@link EXEC_TOKEN_RENEW_MS}, or when `force`d; calls
+ * made while one renewal is under way share it.
+ */
+export function renewingToken(initial, renew, now = Date.now) {
+    let current = initial;
+    let issuedAt = now();
+    let renewing = null;
+    return (force = false) => {
+        if (!force && now() - issuedAt < EXEC_TOKEN_RENEW_MS)
+            return Promise.resolve(current);
+        renewing ??= renew()
+            .then((next) => {
+            current = next;
+            issuedAt = now();
+            return current;
+        })
+            .finally(() => {
+            renewing = null;
+        });
+        return renewing;
+    };
+}
+export function rpcUrlOf(backendUrl) {
+    const url = toHttpUrl(backendUrl);
+    url.pathname = `${url.pathname.replace(/\/$/, '')}/trpc`;
+    url.search = '';
+    url.hash = '';
+    return url.toString();
+}
+/** Asks the backend for the run: its token, scope and `ctx` data. */
+export async function requestExecRun(backendUrl, token, env, instance) {
+    const { response, payload } = await requestJson(apiUrl(backendUrl, 'cli-auth/exec'), {
+        method: 'POST',
+        headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
+        body: JSON.stringify({ environment: env, ...(instance ? { instanceId: instance } : {}) }),
+    });
+    if (response.status === 401)
+        throw new Error('the login was refused: run `superpanel-sdk-runtime login` again');
+    if (!response.ok)
+        throw new Error(`exec: ${payload.error ?? `the backend answered ${response.status}`}`);
+    return payload;
+}
+export async function openExecSession(repoRoot, options) {
+    const backendUrl = resolveBackendUrl(repoRoot, options.url);
+    const authorization = await loadCachedServeAuthorization(backendUrl);
+    if (!authorization)
+        throw new Error('not logged in: run `superpanel-sdk-runtime login` first');
+    // The runtime's own routine lines (each RPC's start and end) are not the caller's: only its warnings show.
+    setRuntimeLogLevel('WARN');
+    const run = await requestExecRun(backendUrl, authorization.token, options.env ?? 'sandbox', options.instance);
+    const token = renewingToken(run.runToken, async () => (run.runToken = (await requestExecRun(backendUrl, authorization.token, options.env ?? 'sandbox', options.instance)).runToken));
+    // Kept fresh while nothing calls (a `mobile` left open): the timer does not keep the process alive.
+    const keepFresh = setInterval(() => void token().catch(() => undefined), 60_000);
+    keepFresh.unref();
+    const data = { ...run.data, config: { ...run.data.config, backendUrl: rpcUrlOf(backendUrl) } };
+    const host = createRpcApiHost({
+        baseUrl: data.config.backendUrl,
+        // Renewed first when it is old (a session left open past its life, the timer held back by a sleep).
+        getToken: () => token(),
+        runtimeVersion: runtimePackageVersion(),
+        runtimeSource: runtimePackageSource(repoRoot),
+    });
+    const ctx = await buildActionContext(data, host);
+    return { repoRoot, backendUrl, loginToken: authorization.token, run, ctx: { ...ctx, api: traceApi(ctx.api, options.record) }, token, close: () => clearInterval(keepFresh) };
+}
+//# sourceMappingURL=session.js.map

package/dist/cli/exec/trace.d.ts

@@ -0,0 +1,18 @@
+/** Every `ctx.api` call of an exec session, recorded: what `calls.jsonl` and an integration test's `calls` hold. */
+/** One `ctx.api` call, as `calls.jsonl` keeps it. */
+export type ApiCall = {
+    at: string;
+    ms: number;
+    call: string;
+    input: unknown;
+    ok: boolean;
+    output?: unknown;
+    error?: string;
+};
+/**
+ * `api` with every method recorded: its path (`db.contact.findMany`, `instances.notify`,
+ * `integration.envs.0.get`), arguments and answer. `then` is left alone, so the object is not taken for a
+ * promise.
+ */
+export declare function traceApi<T extends object>(api: T, record: (call: ApiCall) => void, prefix?: string[]): T;
+//# sourceMappingURL=trace.d.ts.map

package/dist/cli/exec/trace.js

@@ -0,0 +1,52 @@
+/** Every `ctx.api` call of an exec session, recorded: what `calls.jsonl` and an integration test's `calls` hold. */
+/**
+ * `api` with every method recorded: its path (`db.contact.findMany`, `instances.notify`,
+ * `integration.envs.0.get`), arguments and answer. `then` is left alone, so the object is not taken for a
+ * promise.
+ */
+export function traceApi(api, record, prefix = []) {
+    const wrapped = new WeakMap();
+    const wrap = (value, at) => {
+        if (typeof value === 'function') {
+            return (...args) => {
+                const started = Date.now();
+                const call = at.join('.');
+                const input = args.length <= 1 ? args[0] : args;
+                const done = (ok, outcome) => record({ at: new Date(started).toISOString(), ms: Date.now() - started, call, input, ok, ...outcome });
+                try {
+                    const out = value(...args);
+                    if (out && typeof out.then === 'function') {
+                        return out.then((output) => (done(true, { output }), output), (error) => {
+                            done(false, { error: error instanceof Error ? error.message : String(error) });
+                            throw error;
+                        });
+                    }
+                    done(true, { output: out });
+                    return out;
+                }
+                catch (error) {
+                    done(false, { error: error instanceof Error ? error.message : String(error) });
+                    throw error;
+                }
+            };
+        }
+        if (value && typeof value === 'object') {
+            const hit = wrapped.get(value);
+            if (hit)
+                return hit;
+            const proxy = new Proxy(value, {
+                get: (target, key, receiver) => {
+                    const inner = Reflect.get(target, key, receiver);
+                    if (typeof key === 'symbol' || key === 'then')
+                        return inner;
+                    return wrap(inner, [...at, key]);
+                },
+            });
+            wrapped.set(value, proxy);
+            return proxy;
+        }
+        return value;
+    };
+    return wrap(api, prefix);
+}
+//# sourceMappingURL=trace.js.map

package/dist/cli/index.js

@@ -2,7 +2,13 @@
 import { existsSync } from 'node:fs';
 import path from 'node:path';
 import { Command } from 'commander';
+import { runLogin, runLogout, runWhoami } from './auth/index.js';
 import { runCompile } from './compile/index.js';
+import { runExec } from './exec/index.js';
+import { runLogs } from './logs/index.js';
+import { runMobile } from './mobile/index.js';
+import { runTurnCli } from './turns/run.js';
+import { runTurnExport, runTurns } from './turns/index.js';
 import { runServe } from './serve/index.js';
 import { runTypeGen } from './type-gen/index.js';
 function loadCwdEnv() {
@@ -14,7 +20,7 @@ function loadCwdEnv() {
 const program = new Command();
 program
     .name('superpanel-sdk-runtime')
-    .description('Company-repo tooling: type generation and sequence compile')
+    .description('Company-repo tooling: type generation, sequence compile, Local Serve, code snippets and logs')
     .showHelpAfterError()
     .configureHelp({ sortSubcommands: true });
 program
@@ -35,19 +41,116 @@ program
     .action(async (options) => {
     await runCompile(process.cwd(), { sequenceId: options.sequence });
 });
+program
+    .command('exec <file>')
+    .description("Run a code snippet (a .ts file whose default export is (ctx, args) => value) on this machine against an environment's real data; what it writes is written. Its result, every ctx.api call and its logs go to .superpanel/exec/<time>-<name>/")
+    .option('--env <name|id>', 'The environment (not prod)', 'sandbox')
+    .option('--instance <id>', 'Run on this case: its sequence, and writes scoped to it')
+    .option('--args <json>', "The snippet's second argument, as JSON")
+    .option('--json', 'Print only the result as JSON')
+    .option('--url <url>', 'Backend host URL')
+    .action(async (file, options) => {
+    const result = await runExec(process.cwd(), file, options);
+    if (!result.ok)
+        process.exitCode = 1;
+});
+program
+    .command('logs')
+    .description("What this repository's code wrote (ctx.api.log, the page's console, its functions' failures) in an environment, from the platform's log store: oldest first, kept in .superpanel/logs/<time>.jsonl")
+    .option('--env <name|id>', 'The environment (prod too: reading only)', 'sandbox')
+    .option('--since <time>', 'From: 15m, 2h, 3d ago, or ISO 8601 (default: the last hour)')
+    .option('--until <time>', 'Until: the same forms')
+    .option('--instance <id>', "One case's lines")
+    .option('--run <id>', "One run's lines")
+    .option('--contact <id>', "One contact's lines")
+    .option('--sequence <name>', "One sequence's lines")
+    .option('--request <id>', "One request's lines")
+    .option('--level <level>', 'warn: warn and error; or a list: info,error')
+    .option('--search <text>', 'Text anywhere in the line or its data')
+    .option('--limit <n>', 'Lines at most (default 200, at most 500)', (value) => Number(value))
+    .option('--follow', 'Then keep showing new lines as they come')
+    .option('--json', 'One JSON per line')
+    .option('--url <url>', 'Backend host URL')
+    .action(async (options) => {
+    await runLogs(process.cwd(), options);
+});
+program
+    .command('turns [action] [turnId]')
+    .description("The turns of a case, a run or a call in a non-prod environment, one line each (what the customer said, what the AI said and did); `turns export <turnId>` writes one turn and what it began with to .superpanel/turns/<turnId>/")
+    .option('--env <name|id>', 'The environment (not prod)', 'sandbox')
+    .option('--instance <id>', "One case's turns")
+    .option('--call <id>', "One call's turns")
+    .option('--run <id>', "One run's turns")
+    .option('--since <time>', 'From: 15m, 2h, 3d ago, or ISO 8601')
+    .option('--limit <n>', 'Turns at most (default and at most 200)', (value) => Number(value))
+    .option('--out <dir>', 'export: the directory to write (default .superpanel/turns/<turnId>/)')
+    .option('--json', 'One JSON per turn')
+    .option('--url <url>', 'Backend host URL')
+    .action(async (action, turnId, options) => {
+    if (action === undefined)
+        return runTurns(process.cwd(), options);
+    if (action !== 'export' || !turnId)
+        throw new Error('turns: `turns --instance <id>` lists, `turns export <turnId>` writes one');
+    return runTurnExport(process.cwd(), turnId, options);
+});
+program
+    .command('turn')
+    .description("One turn as a shadow (68 §8), with this repository's code: from a turn that ran (--from: its id or exported directory) or on a case now (--instance, --say); what it said, pressed and wrote, nothing kept")
+    .option('--env <name|id>', 'The environment (not prod)', 'sandbox')
+    .option('--from <turnId|dir>', 'Start where this turn started')
+    .option('--instance <id>', 'The case, as it is now')
+    .option('--channel <channel>', 'sms, email or call (with --instance; default sms)')
+    .option('--say <text>', "What the customer says (with --from: in place of what they said then)")
+    .option('--caller <id>', "The conversation's contact (default: the case's subject)")
+    .option('--repeat <n>', 'Run it n times (1-10)', (value) => Number(value))
+    .option('--json', 'One JSON per run')
+    .option('--url <url>', 'Backend host URL')
+    .action(async (options) => {
+    await runTurnCli(process.cwd(), options);
+});
+program
+    .command('mobile')
+    .description("A test customer's phone on a non-prod environment, served by this repository's code: call a line and talk in text, text and email it, and get its texts, emails and calls as they come (68 §5.4); /help inside")
+    .option('--env <name|id>', 'The environment (not prod)', 'sandbox')
+    .option('--line <name>', 'The line you call and text (default Main line)')
+    .option('--mailbox <name>', 'The mailbox you email (default Support)')
+    .option('--new', "A new test customer instead of this repository's last one")
+    .option('--url <url>', 'Backend host URL')
+    .action(async (options) => {
+    await runMobile(process.cwd(), options);
+});
+program
+    .command('login')
+    .description('Authorize Local Serve and cache the credential')
+    .option('--url <url>', 'Backend host URL')
+    .action(async (options) => {
+    await runLogin(process.cwd(), options);
+});
+program
+    .command('logout')
+    .description('Clear the cached Local Serve credential')
+    .option('--url <url>', 'Backend host URL')
+    .action(async (options) => {
+    await runLogout(process.cwd(), options);
+});
+program
+    .command('whoami')
+    .description('Show the cached Local Serve login')
+    .option('--url <url>', 'Backend host URL')
+    .action(async (options) => {
+    await runWhoami(process.cwd(), options);
+});
 program
     .command('serve')
-    .description('Watch local sequences and overlay them onto a backend over WebSocket')
-    .option('--url <url>', 'Backend host or overlay WebSocket URL (env SUPERPANEL_SDK_BACKEND_URL)')
-    .option('--api-key <key>', 'Company API key (env SUPERPANEL_SDK_API_KEY)')
-    .option('--company <id>', 'Company id (env SUPERPANEL_SDK_COMPANY_ID)')
-    .option('--sequence <id>', 'Serve a single sequence (default: all with slots)')
+    .description('Watch the whole repository and serve it in place of an environment\'s live release, over WebSocket')
+    .option('--url <url>', 'Backend host URL (env SUPERPANEL_SDK_BACKEND_URL)')
+    .option('--no-open', 'Copy the authorization URL to the clipboard instead of opening a browser')
+    .option('--environment <id>', 'Target non-production environment id (prompts in a terminal if omitted)')
     .action(async (options) => {
     await runServe(process.cwd(), {
         url: options.url,
-        apiKey: options.apiKey,
-        companyId: options.company,
-        sequenceIds: options.sequence ? [options.sequence] : undefined,
+        openBrowser: options.open,
+        environment: options.environment,
     });
 });
 async function main() {

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

@@ -0,0 +1,47 @@
+export type LogsQuery = {
+    env?: string;
+    since?: string;
+    until?: string;
+    instance?: string;
+    run?: string;
+    contact?: string;
+    sequence?: string;
+    request?: string;
+    level?: string;
+    search?: string;
+    limit?: number;
+};
+export type LogLine = {
+    id: string;
+    at: string;
+    level: string;
+    message: string | null;
+    tags: string[];
+    sequence: string | null;
+    contactId: string | null;
+    requestId: string | null;
+    data: unknown;
+};
+/** `15m`, `2h`, `3d` back from `now`, or an ISO time, as ISO; undefined when not given. */
+export declare function timeOf(value: string | undefined, now?: number): string | undefined;
+/** `--level warn`: that level and above; `--level info,error`: those. */
+export declare function levelsOf(value: string | undefined): string[] | undefined;
+/** One line as the terminal shows it: time, level, sequence, message, its data. */
+export declare function formatLine(line: LogLine): string;
+/** A logs reader as the CLI's login: one read of the window asked. */
+export declare function openLogReader(repoRoot: string, url?: string): Promise<(query: LogsQuery & {
+    order?: 'asc' | 'desc';
+}) => Promise<{
+    environment: {
+        id: string;
+        name: string;
+    };
+    lines: LogLine[];
+    hasMore: boolean;
+}>>;
+export declare function runLogs(repoRoot: string, query: LogsQuery & {
+    follow?: boolean;
+    json?: boolean;
+    url?: string;
+}): Promise<void>;
+//# sourceMappingURL=index.d.ts.map

package/dist/cli/logs/index.js

@@ -0,0 +1,113 @@
+/**
+ * `logs`: what the repository's code wrote (`ctx.api.log`, the page's `console`, its functions' failures)
+ * in one environment, read from the platform's log store on demand as the CLI's login (the backend's
+ * `logging/cli-logs.ts`). Nothing is collected: each read names a window and takes a page, and `--follow`
+ * reads only what came after the last line it showed. Lines are shown oldest first and kept in
+ * `.superpanel/logs/<time>.jsonl`, one JSON per line, for `grep` / `jq`.
+ */
+import { appendFileSync, mkdirSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { loadCachedServeAuthorization, resolveBackendUrl } from '../auth/auth.js';
+import { apiUrl } from '../auth/http.js';
+const LEVELS = ['debug', 'info', 'warn', 'error'];
+/** `15m`, `2h`, `3d` back from `now`, or an ISO time, as ISO; undefined when not given. */
+export function timeOf(value, now = Date.now()) {
+    if (!value)
+        return undefined;
+    const ago = /^(\d+)\s*(s|m|h|d)$/.exec(value.trim());
+    if (ago) {
+        const unit = { s: 1_000, m: 60_000, h: 3_600_000, d: 86_400_000 }[ago[2]];
+        return new Date(now - Number(ago[1]) * unit).toISOString();
+    }
+    const at = Date.parse(value);
+    if (Number.isNaN(at))
+        throw new Error(`${value}: a time is 15m, 2h, 3d (that long ago) or ISO 8601`);
+    return new Date(at).toISOString();
+}
+/** `--level warn`: that level and above; `--level info,error`: those. */
+export function levelsOf(value) {
+    if (!value)
+        return undefined;
+    const asked = value.split(',').map((level) => level.trim().toLowerCase()).filter(Boolean);
+    for (const level of asked)
+        if (!LEVELS.includes(level))
+            throw new Error(`--level: ${level} is not one of ${LEVELS.join(', ')}`);
+    return asked.length === 1 ? LEVELS.slice(LEVELS.indexOf(asked[0])) : asked;
+}
+/** One line as the terminal shows it: time, level, sequence, message, its data. */
+export function formatLine(line) {
+    const time = line.at.replace('T', ' ').replace(/Z$/, '');
+    const data = line.data && (typeof line.data !== 'object' || Object.keys(line.data).length > 0) ? ` ${typeof line.data === 'string' ? line.data : JSON.stringify(line.data)}` : '';
+    return `${time} ${line.level.toUpperCase().padEnd(5)} ${line.sequence ? `[${line.sequence}] ` : ''}${line.message ?? ''}${data}`;
+}
+/** A logs reader as the CLI's login: one read of the window asked. */
+export async function openLogReader(repoRoot, url) {
+    const backendUrl = resolveBackendUrl(repoRoot, url);
+    const authorization = await loadCachedServeAuthorization(backendUrl);
+    if (!authorization)
+        throw new Error('not logged in: run `superpanel-sdk-runtime login` first');
+    return async (query) => {
+        const response = await fetch(apiUrl(backendUrl, 'cli-auth/logs'), {
+            method: 'POST',
+            headers: { Authorization: `Bearer ${authorization.token}`, 'Content-Type': 'application/json' },
+            body: JSON.stringify({
+                environment: query.env ?? 'sandbox',
+                ...(timeOf(query.since) ? { since: timeOf(query.since) } : {}),
+                ...(timeOf(query.until) ? { until: timeOf(query.until) } : {}),
+                ...(query.instance ? { instanceId: query.instance } : {}),
+                ...(query.run ? { runId: query.run } : {}),
+                ...(query.contact ? { contactId: query.contact } : {}),
+                ...(query.sequence ? { sequence: query.sequence } : {}),
+                ...(query.request ? { requestId: query.request } : {}),
+                ...(levelsOf(query.level) ? { levels: levelsOf(query.level) } : {}),
+                ...(query.search ? { search: query.search } : {}),
+                ...(query.order ? { order: query.order } : {}),
+                ...(query.limit ? { limit: query.limit } : {}),
+            }),
+            signal: AbortSignal.timeout(60_000),
+        });
+        const payload = (await response.json().catch(() => ({})));
+        if (response.status === 401)
+            throw new Error('the login was refused: run `superpanel-sdk-runtime login` again');
+        if (!response.ok)
+            throw new Error(`logs: ${payload.error ?? `the backend answered ${response.status}`}`);
+        return payload;
+    };
+}
+function stamp(date) {
+    const pad = (n) => String(n).padStart(2, '0');
+    return `${date.getFullYear()}${pad(date.getMonth() + 1)}${pad(date.getDate())}-${pad(date.getHours())}${pad(date.getMinutes())}${pad(date.getSeconds())}`;
+}
+export async function runLogs(repoRoot, query) {
+    const read = await openLogReader(repoRoot, query.url);
+    const dir = path.join(repoRoot, '.superpanel', 'logs');
+    mkdirSync(dir, { recursive: true });
+    const file = path.join(dir, `${stamp(new Date())}.jsonl`);
+    writeFileSync(file, '');
+    const show = (line) => {
+        appendFileSync(file, `${JSON.stringify(line)}\n`);
+        process.stdout.write(`${query.json ? JSON.stringify(line) : formatLine(line)}\n`);
+    };
+    // The latest page, shown oldest first.
+    const first = await read({ ...query, order: 'desc' });
+    const lines = [...first.lines].reverse();
+    lines.forEach(show);
+    process.stderr.write(`${lines.length} line${lines.length === 1 ? '' : 's'} from ${first.environment.name}${first.hasMore ? ` (more before: narrow it, or --since / --limit)` : ''}; kept in ${path.relative(repoRoot, file)}\n`);
+    if (!query.follow)
+        return;
+    // Then what comes after the last line shown, every few seconds, until stopped.
+    let after = lines.at(-1)?.at ?? new Date().toISOString();
+    const seen = new Set(lines.map((line) => line.id));
+    for (;;) {
+        await new Promise((resolve) => setTimeout(resolve, 3_000));
+        const next = await read({ ...query, since: after, until: undefined, order: 'asc' });
+        for (const line of next.lines) {
+            if (seen.has(line.id))
+                continue;
+            seen.add(line.id);
+            show(line);
+            after = line.at;
+        }
+    }
+}
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1,12 @@
+export type MobileOptions = {
+    env?: string;
+    url?: string;
+    /** The line calls and texts go to (its name or number); `Main line` when left out. */
+    line?: string;
+    /** The mailbox emails go to (its name or address); `Support` when left out. */
+    mailbox?: string;
+    /** A new test customer instead of this repository's last one for the environment. */
+    new?: boolean;
+};
+export declare function runMobile(repoRoot: string, options: MobileOptions): Promise<void>;
+//# sourceMappingURL=index.d.ts.map