@3minapi/cli 0.0.0-stage → 0.22.0

package/dist/modules/workers/builtin/host-identity.js

@@ -0,0 +1,59 @@
+import { createHash } from 'node:crypto';
+import { StopError, builtinResultsName } from "../../../core/domain/index.js";
+export const HOST_META = {
+    id: 'host_id',
+    name: 'host_name',
+    tokenFp: 'host_token_fp'
+};
+export function tokenFingerprint(token) {
+    return createHash('sha256').update(token).digest('hex').slice(0, 12);
+}
+export function cacheHostIdentity(db, token, host, now) {
+    try {
+        const previous = db.getMeta(HOST_META.id);
+        db.setMetas({
+            [HOST_META.id]: host.id,
+            [HOST_META.name]: host.name,
+            [HOST_META.tokenFp]: tokenFingerprint(token)
+        }, now);
+        return previous !== null && previous !== host.id ? previous : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function hostChangedWarning(previousId, host) {
+    return (`this token is for host "${host.name}" (${host.id}); this PC was host ${previousId}. ` +
+        "The previous host's task history and saved results stay on this PC; remote AIs on the new host " +
+        "cannot read those results. Remove the task history with '3minapi tasks prune' if you no longer need it.");
+}
+export function cachedHostIdentity(db, token) {
+    if (db.getMeta(HOST_META.tokenFp) !== tokenFingerprint(token))
+        return null;
+    const id = db.getMeta(HOST_META.id);
+    const name = db.getMeta(HOST_META.name);
+    return id && name ? { id, name } : null;
+}
+export async function resolveHostIdentity(db, api, token, now) {
+    const cached = cachedHostIdentity(db, token);
+    if (cached)
+        return { host: cached };
+    try {
+        const res = await api.getHost();
+        const host = { id: res.host.id, name: res.host.name };
+        const previous = cacheHostIdentity(db, token, host, now);
+        return previous === null ? { host } : { host, previousHostId: previous };
+    }
+    catch (err) {
+        if (err instanceof StopError)
+            throw err;
+        return { host: null, error: err.message };
+    }
+}
+export function builtinResultsSpec(host) {
+    return {
+        name: builtinResultsName(host.id),
+        description: `Built-in reader for the task results saved on host ${JSON.stringify(host.name)}. ` +
+            'input: {"op":"describe"|"query"|"read", …} — see help(tasks) for the fields and examples.'
+    };
+}

package/dist/modules/workers/builtin/results-worker.js

@@ -0,0 +1,37 @@
+import { RESULTS_QUERY_TIMEOUT_MS } from "../../../core/domain/index.js";
+import { runReaderChild } from "../results/query.js";
+import { parseReaderInput } from "../results/reader-input.js";
+import { resultsDbPath } from "../results/store.js";
+export function resultsWorker(root, hostId, timeoutMs = RESULTS_QUERY_TIMEOUT_MS) {
+    return async (input, signal) => {
+        const parsed = parseReaderInput(input);
+        if (!parsed.ok)
+            return { status: 'failed', reason: 'invalid_input', message: parsed.message };
+        let r;
+        try {
+            r = await runReaderChild(root, hostId, parsed.req, timeoutMs, signal);
+        }
+        catch {
+            return {
+                status: 'failed',
+                reason: 'query_error',
+                message: "could not read the saved results on the user's PC"
+            };
+        }
+        if (r === 'cancelled')
+            return { status: 'failed', reason: 'query_error', message: 'cancelled' };
+        if (r === 'timeout') {
+            return {
+                status: 'failed',
+                reason: 'timeout',
+                message: `did not finish within ${timeoutMs / 1000}s — narrow the scope or aggregate in SQL`
+            };
+        }
+        if (!r.ok)
+            return { status: 'failed', reason: r.reason, message: withoutPaths(root, r.message) };
+        return { status: 'completed', resultJson: JSON.stringify(r.result) };
+    };
+}
+function withoutPaths(root, message) {
+    return message.split(resultsDbPath(root)).join('data.db').split(root).join('<project>');
+}

package/dist/modules/workers/local-server.js

@@ -0,0 +1,244 @@
+import { createHash, createHmac, randomUUID, timingSafeEqual } from 'node:crypto';
+import { createServer } from 'node:http';
+import { PUSH_TIMESTAMP_TOLERANCE_S, REPORT_MAX_BYTES, WORKER_KEY_ENV, WORKER_SECRET_ENV, isPullWorkerName } from "../../core/domain/index.js";
+import { resolveWorkerFile } from "./runtime/resolve.js";
+const TASK_PATH = /^\/task\/([^/]+)$/;
+const UNAUTHORIZED = { status: 401, body: { success: false, error: 'unauthorized' } };
+export async function startLocalServer(opts) {
+    const tokenDigest = sha256(opts.token);
+    const server = createServer((req, res) => {
+        handle(opts, tokenDigest, req, actualPort)
+            .then((reply) => send(res, reply))
+            .catch((err) => {
+            opts.onError?.(err);
+            send(res, { status: 500, body: error('internal error') });
+        });
+    });
+    const host = opts.public ? '0.0.0.0' : '127.0.0.1';
+    await new Promise((resolve, reject) => {
+        server.once('error', reject);
+        server.listen(opts.port, host, () => {
+            server.off('error', reject);
+            resolve();
+        });
+    }).catch((err) => {
+        if (err.code === 'EADDRINUSE') {
+            throw Object.assign(new Error(`port ${opts.port} is already in use — pick another with --port`), {
+                code: err.code
+            });
+        }
+        throw err;
+    });
+    const actualPort = server.address().port;
+    return {
+        url: `http://${opts.public ? '0.0.0.0' : '127.0.0.1'}:${actualPort}`,
+        port: actualPort,
+        close: () => new Promise((resolve) => {
+            server.closeAllConnections();
+            server.close(() => resolve());
+        })
+    };
+}
+async function handle(opts, tokenDigest, req, port) {
+    const url = new URL(req.url ?? '/', 'http://localhost');
+    if (!opts.public) {
+        const denied = localGuard(req, port);
+        if (denied)
+            return denied;
+    }
+    if (url.pathname === '/health') {
+        if (req.method !== 'GET')
+            return { status: 405, body: error('use GET') };
+        return { status: 200, body: { ok: true, version: opts.version } };
+    }
+    const match = TASK_PATH.exec(url.pathname);
+    if (!match)
+        return { status: 404, body: error('not found. Use POST /task/<worker>') };
+    if (req.method !== 'POST')
+        return { status: 405, body: error('use POST') };
+    let name;
+    try {
+        name = decodeURIComponent(match[1]);
+    }
+    catch {
+        return { status: 404, body: error('not found. Use POST /task/<worker>') };
+    }
+    let secrets = null;
+    if (opts.public) {
+        if (!isPullWorkerName(name))
+            return { status: 404, body: error(`unknown worker "${name}"`) };
+        const now = opts.nowSeconds?.() ?? Math.floor(Date.now() / 1000);
+        const headers = signatureHeaders(req, now);
+        if (headers === 'missing')
+            return UNAUTHORIZED;
+        if (headers !== null) {
+            opts.onRejected?.(name, headers);
+            return UNAUTHORIZED;
+        }
+        const env = typeof opts.env === 'function' ? opts.env() : opts.env;
+        const secret = env[WORKER_SECRET_ENV(name)];
+        const key = env[WORKER_KEY_ENV(name)];
+        if (!secret || !key) {
+            opts.onRejected?.(name, `not configured as a public worker (${WORKER_SECRET_ENV(name)} / ${WORKER_KEY_ENV(name)})`);
+            return UNAUTHORIZED;
+        }
+        secrets = { secret, key };
+    }
+    if (!opts.public && !bearerMatches(req.headers.authorization, tokenDigest)) {
+        return {
+            status: 401,
+            body: error('missing or wrong local server token (Authorization: Bearer <token>)')
+        };
+    }
+    if (!/^application\/json\b/i.test(req.headers['content-type'] ?? '')) {
+        return { status: 415, body: error('Content-Type must be application/json') };
+    }
+    const raw = await readBody(req, REPORT_MAX_BYTES);
+    if (raw === null)
+        return { status: 413, body: error(`body exceeds ${REPORT_MAX_BYTES} bytes`) };
+    let reporter = null;
+    if (secrets) {
+        const now = opts.nowSeconds?.() ?? Math.floor(Date.now() / 1000);
+        const invalid = verifySignature(secrets.secret, req, raw, now);
+        if (invalid) {
+            opts.onRejected?.(name, invalid);
+            return UNAUTHORIZED;
+        }
+        reporter = opts.reporterFor(secrets.key);
+    }
+    let body;
+    try {
+        body = JSON.parse(raw.toString('utf8'));
+    }
+    catch {
+        return { status: 400, body: error('body is not valid JSON') };
+    }
+    const task = toEnvelope(body, name, req, opts.public);
+    if (typeof task === 'string')
+        return { status: 400, body: error(task) };
+    const found = resolveWorkerFile(opts.workersDir, name);
+    if (!found.ok && found.reason === 'worker_not_found')
+        return { status: 404, body: error(found.message) };
+    const inactive = opts.inactive?.(name) ?? null;
+    if (inactive !== null)
+        return { status: 409, body: error(inactive) };
+    opts.onTask(task, reporter);
+    return { status: 202, body: { success: true, task_id: task.task_id } };
+}
+function localGuard(req, port) {
+    const allowed = [`127.0.0.1:${port}`, `localhost:${port}`, `[::1]:${port}`];
+    const host = (req.headers.host ?? '').toLowerCase();
+    if (!allowed.includes(host)) {
+        return { status: 403, body: error('Host header must be 127.0.0.1 or localhost') };
+    }
+    if (req.headers.origin !== undefined) {
+        return { status: 403, body: error('requests from web pages are not accepted') };
+    }
+    const site = req.headers['sec-fetch-site'];
+    if (site !== undefined && site !== 'none') {
+        return { status: 403, body: error('requests from web pages are not accepted') };
+    }
+    return null;
+}
+function toEnvelope(body, worker, req, isPublic) {
+    if (typeof body !== 'object' || body === null || Array.isArray(body))
+        return 'body must be a JSON object';
+    const b = body;
+    const attempt = Number(req.headers['x-3minapi-delivery-attempt'] ?? 1);
+    const delivery_attempt = Number.isInteger(attempt) && attempt > 0 ? attempt : 1;
+    if (b.type === 'task.created' && typeof b.data === 'object' && b.data !== null) {
+        const d = b.data;
+        if (isPublic) {
+            if (typeof d.task_id !== 'string' || d.task_id !== req.headers['webhook-id']) {
+                return 'data.task_id must match the webhook-id header';
+            }
+            if (typeof d.callback_url !== 'string')
+                return 'data.callback_url is required';
+        }
+        return {
+            task_id: isPublic ? d.task_id : randomUUID(),
+            worker,
+            input: d.input ?? {},
+            callback_url: isPublic ? d.callback_url : null,
+            lease_id: null,
+            delivery_attempt,
+            source: isPublic ? 'public' : 'serve'
+        };
+    }
+    if (isPublic)
+        return 'expected a task.created envelope';
+    if (!('input' in b))
+        return 'expected {"input": ...} or a task.created envelope';
+    return {
+        task_id: randomUUID(),
+        worker,
+        input: b.input,
+        callback_url: null,
+        lease_id: null,
+        delivery_attempt,
+        source: 'serve'
+    };
+}
+function signatureHeaders(req, nowSeconds) {
+    const { 'webhook-id': id, 'webhook-timestamp': ts, 'webhook-signature': sig } = req.headers;
+    if (typeof id !== 'string' || typeof ts !== 'string' || typeof sig !== 'string')
+        return 'missing';
+    const t = Number(ts);
+    if (!Number.isInteger(t) || Math.abs(nowSeconds - t) > PUSH_TIMESTAMP_TOLERANCE_S) {
+        return 'webhook-timestamp is outside the allowed window';
+    }
+    return null;
+}
+export function verifySignature(secret, req, raw, nowSeconds) {
+    const id = req.headers['webhook-id'];
+    const ts = req.headers['webhook-timestamp'];
+    const sig = req.headers['webhook-signature'];
+    if (typeof id !== 'string' || typeof ts !== 'string' || typeof sig !== 'string') {
+        return 'missing webhook-id / webhook-timestamp / webhook-signature headers';
+    }
+    const t = Number(ts);
+    if (!Number.isInteger(t) || Math.abs(nowSeconds - t) > PUSH_TIMESTAMP_TOLERANCE_S) {
+        return 'webhook-timestamp is outside the allowed window';
+    }
+    const key = Buffer.from(secret.startsWith('whsec_') ? secret.slice(6) : secret, 'base64');
+    const expected = createHmac('sha256', key).update(`${id}.${ts}.`).update(raw).digest();
+    for (const part of sig.split(' ')) {
+        const [version, value] = part.split(',', 2);
+        if (version !== 'v1' || !value)
+            continue;
+        const given = Buffer.from(value, 'base64');
+        if (given.length === expected.length && timingSafeEqual(given, expected))
+            return null;
+    }
+    return 'webhook-signature does not match';
+}
+function bearerMatches(header, digest) {
+    const m = header?.match(/^Bearer\s+(\S+)$/i);
+    return m !== null && m !== undefined && timingSafeEqual(sha256(m[1]), digest);
+}
+function sha256(value) {
+    return createHash('sha256').update(value).digest();
+}
+async function readBody(req, max) {
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of req) {
+        size += chunk.length;
+        if (size > max * 4) {
+            req.destroy();
+            return null;
+        }
+        if (size <= max)
+            chunks.push(chunk);
+    }
+    return size > max ? null : Buffer.concat(chunks);
+}
+function send(res, reply) {
+    if (res.headersSent || res.destroyed)
+        return;
+    res.writeHead(reply.status, { 'content-type': 'application/json; charset=utf-8' });
+    res.end(JSON.stringify(reply.body));
+}
+function error(message) {
+    return { success: false, error: message };
+}

package/dist/modules/workers/module.js

@@ -0,0 +1,98 @@
+import { PULL_MAX_LIMIT, isPullWorkerName } from "../../core/domain/index.js";
+import { checkRepeat } from "./repeat-scheduler.js";
+export class WorkersModule {
+    topics = ['workers'];
+    opts;
+    repeatsStarted = false;
+    slotFree = null;
+    constructor(opts) {
+        this.opts = opts;
+    }
+    get activeCount() {
+        return this.opts.workers.activeCount;
+    }
+    beforePull() {
+        return this.opts.runner.flushPending();
+    }
+    flushPending() {
+        return this.opts.runner.flushPending();
+    }
+    onSlotFree(cb) {
+        this.slotFree = cb;
+    }
+    notifySlotFree() {
+        this.slotFree?.();
+    }
+    pullMax() {
+        return Math.min(PULL_MAX_LIMIT, this.opts.runner.free);
+    }
+    onPull(res) {
+        const { api, runner, logger, workers } = this.opts;
+        const { deleted, unregistered } = workers.applyServerList(res.workers.map((w) => w.name));
+        if (unregistered.length > 0) {
+            logger.warn('workers that could not load are not registered on the server', {
+                workers: unregistered
+            });
+            this.opts.onWorkersUnregistered?.(unregistered);
+        }
+        if (deleted.length > 0) {
+            logger.warn('workers deleted on the server; reload or restart start to register them again', {
+                workers: deleted
+            });
+            this.opts.onWorkersDeleted?.(deleted);
+            runner.dropRepeats(deleted);
+        }
+        for (const id of res.cancelled)
+            runner.cancel(id);
+        for (const t of res.tasks) {
+            if (!isPullWorkerName(t.worker)) {
+                logger.warn('ignored a task with an invalid worker name', {
+                    task_id: String(t.data?.task_id)
+                });
+                continue;
+            }
+            const repeat = t.data.repeat == null ? null : checkRepeat(t.data.repeat);
+            if (t.data.repeat != null && repeat === null) {
+                logger.warn('ignored a repeating task with invalid settings', {
+                    task_id: String(t.data?.task_id)
+                });
+                continue;
+            }
+            void runner.handle({
+                task_id: t.data.task_id,
+                worker: t.worker,
+                input: t.data.input,
+                callback_url: t.data.callback_url,
+                lease_id: t.lease_id,
+                delivery_attempt: t.delivery_attempt,
+                source: 'pull',
+                ...(repeat ? { repeat } : {})
+            }, api, { ack: true });
+        }
+        if (!this.repeatsStarted) {
+            this.repeatsStarted = true;
+            runner.startRepeats();
+        }
+    }
+    dropLocal(names) {
+        const dropped = this.opts.workers.dropLocal(names);
+        if (dropped.length === 0)
+            return;
+        this.opts.logger.info('workers deleted with worker delete; turned off', { workers: dropped });
+        this.opts.onWorkersDropped?.(dropped);
+        this.opts.runner.dropRepeats(dropped);
+    }
+    async resync() {
+        await this.opts.resync?.();
+    }
+    halt(reason) {
+        return this.opts.runner.halt(reason);
+    }
+    async shutdown() {
+        await this.opts.runner.shutdown();
+        await this.opts.runner.flushPending();
+    }
+    ended() {
+        return { ended: 'no_active_workers', deletedWorkers: this.opts.workers.deletedNames() };
+    }
+}

package/dist/modules/workers/reload-result.js

@@ -0,0 +1,16 @@
+import { formatCount } from "../../core/text.js";
+export function reloadLines(result) {
+    const lines = [];
+    const registered = [
+        ...result.created.map((n) => `${n} (new)`),
+        ...result.updated.map((n) => `${n} (updated)`)
+    ];
+    if (registered.length > 0)
+        lines.push(`registered  ${registered.join(', ')}`);
+    for (const r of result.rejected)
+        lines.push(`rejected    ${r.name} — ${r.error}`);
+    for (const w of result.notLoaded)
+        lines.push(`not loaded  ${w.name} — ${w.message}`);
+    lines.push(`workers     ${result.active.length} active (${result.active.join(', ') || 'none'})`, `quota       ${formatCount(result.quota.remaining)} of ${formatCount(result.quota.limit)} calls left`);
+    return lines;
+}

package/dist/modules/workers/repeat-scheduler.js

@@ -0,0 +1,165 @@
+import { REPEAT_INTERVAL_MAX_S, REPEAT_INTERVAL_MIN_S, REPEAT_TICK_MS } from "../../core/domain/index.js";
+export class RepeatScheduler {
+    opts;
+    entries = new Map();
+    timer = null;
+    stopped = false;
+    loaded = false;
+    constructor(opts) {
+        this.opts = opts;
+    }
+    has(taskId) {
+        return this.entries.has(taskId);
+    }
+    get size() {
+        return this.entries.size;
+    }
+    add(taskId, worker, settings, doneRuns = 0) {
+        if (this.stopped || this.entries.has(taskId))
+            return;
+        const entry = {
+            taskId,
+            worker,
+            intervalMs: settings.interval_seconds * 1000,
+            runNo: doneRuns,
+            nextAt: this.opts.now(),
+            busy: false
+        };
+        this.entries.set(taskId, entry);
+        this.ensureTimer();
+        this.due(entry, this.opts.now());
+    }
+    load() {
+        if (this.stopped || this.loaded)
+            return;
+        this.loaded = true;
+        const now = this.opts.now();
+        for (const row of this.opts.db.repeatTasks()) {
+            if (this.entries.has(row.task_id))
+                continue;
+            const settings = parseSettings(row.repeat);
+            if (!settings) {
+                this.opts.logger.warn('ignored a repeating task with unreadable settings', {
+                    task_id: row.task_id
+                });
+                continue;
+            }
+            this.entries.set(row.task_id, {
+                taskId: row.task_id,
+                worker: row.worker,
+                intervalMs: settings.interval_seconds * 1000,
+                runNo: Math.max(row.run_no ?? 0, row.runs ?? 0),
+                nextAt: row.next_at == null || row.next_at < now ? now : row.next_at,
+                busy: false
+            });
+        }
+        if (this.entries.size > 0) {
+            this.ensureTimer();
+            this.tick();
+        }
+    }
+    remove(taskId) {
+        this.entries.delete(taskId);
+    }
+    dropWorkers(names) {
+        const gone = new Set(names);
+        const ids = [];
+        for (const e of this.entries.values()) {
+            if (gone.has(e.worker))
+                ids.push(e.taskId);
+        }
+        for (const id of ids)
+            this.entries.delete(id);
+        return ids;
+    }
+    stop() {
+        this.stopped = true;
+        this.timer?.clear();
+        this.timer = null;
+    }
+    snapshot() {
+        return [...this.entries.values()].map((e) => ({ ...e }));
+    }
+    tick() {
+        if (this.stopped)
+            return;
+        const now = this.opts.now();
+        for (const entry of [...this.entries.values()]) {
+            if (entry.nextAt <= now)
+                this.due(entry, now);
+        }
+    }
+    due(entry, now) {
+        let next = entry.nextAt + entry.intervalMs;
+        if (next <= now)
+            next = now + entry.intervalMs;
+        entry.nextAt = next;
+        this.persistNextAt(entry);
+        if (entry.busy) {
+            this.opts.logger.info('repeat run skipped; the previous run has not finished', {
+                task_id: entry.taskId,
+                worker: entry.worker,
+                run_no: entry.runNo
+            });
+            return;
+        }
+        entry.busy = true;
+        entry.runNo += 1;
+        void this.opts
+            .run(entry.taskId, entry.runNo)
+            .catch((err) => {
+            this.opts.logger.error('repeat run failed to start', {
+                task_id: entry.taskId,
+                message: err?.stack ?? String(err)
+            });
+        })
+            .finally(() => {
+            entry.busy = false;
+        });
+    }
+    persistNextAt(entry) {
+        try {
+            this.opts.db.setNextAt(entry.taskId, entry.nextAt);
+        }
+        catch (err) {
+            this.opts.logger.warn('could not record the next run time', {
+                task_id: entry.taskId,
+                message: err.message
+            });
+        }
+    }
+    ensureTimer() {
+        if (this.timer || this.stopped)
+            return;
+        const every = this.opts.every ??
+            ((fn, ms) => {
+                const t = setInterval(fn, ms);
+                t.unref();
+                return { clear: () => clearInterval(t) };
+            });
+        this.timer = every(() => this.tick(), REPEAT_TICK_MS);
+    }
+}
+export function parseSettings(json) {
+    if (!json)
+        return null;
+    try {
+        return checkRepeat(JSON.parse(json));
+    }
+    catch {
+        return null;
+    }
+}
+export function checkRepeat(value) {
+    if (typeof value !== 'object' || value === null)
+        return null;
+    const { interval_seconds: every, max_runs: max } = value;
+    if (!Number.isInteger(every))
+        return null;
+    const seconds = every;
+    if (seconds < REPEAT_INTERVAL_MIN_S || seconds > REPEAT_INTERVAL_MAX_S)
+        return null;
+    if (max !== undefined && !(Number.isSafeInteger(max) && max > 0))
+        return null;
+    return { interval_seconds: seconds, ...(max === undefined ? {} : { max_runs: max }) };
+}

package/dist/modules/workers/results/missing-paths.js

@@ -0,0 +1,66 @@
+export const MISSING_PATHS_MAX = 10;
+export function sqlJsonPaths(sql) {
+    const out = [];
+    for (const m of sql.matchAll(/'((?:[^']|'')*)'/g)) {
+        const literal = m[1].replace(/''/g, "'");
+        if (literal.length <= 1 || !literal.startsWith('$') || out.includes(literal))
+            continue;
+        if (isPathPosition(sql, m.index ?? 0))
+            out.push(literal);
+    }
+    return out;
+}
+function isPathPosition(sql, at) {
+    const before = sql.slice(0, at).trimEnd();
+    if (before.endsWith('->') || before.endsWith('->>'))
+        return true;
+    if (!before.endsWith(','))
+        return false;
+    let depth = 0;
+    let inString = false;
+    for (let i = before.length - 2; i >= 0; i--) {
+        const ch = before[i];
+        if (ch === "'")
+            inString = !inString;
+        if (inString)
+            continue;
+        if (ch === ')')
+            depth++;
+        else if (ch === '(') {
+            if (depth === 0)
+                return /json_\w+\s*$/i.test(before.slice(0, i));
+            depth--;
+        }
+    }
+    return false;
+}
+function normalize(path) {
+    return path.replace(/\[(?:\d+|#[^\]]*)\]/g, '[*]');
+}
+export function missingPaths(sql, known) {
+    const missing = [];
+    for (const raw of sqlJsonPaths(sql)) {
+        const path = normalize(raw);
+        if (known.has(path))
+            continue;
+        const tail = path.slice(1);
+        if (tail === '' || !(tail.startsWith('.') || tail.startsWith('[')))
+            continue;
+        let found = false;
+        for (const k of known) {
+            if (k.endsWith(tail)) {
+                found = true;
+                break;
+            }
+        }
+        if (!found)
+            missing.push(raw);
+    }
+    return missing;
+}
+export function missingPathsWarning(missing) {
+    const shown = missing.slice(0, MISSING_PATHS_MAX);
+    const more = missing.length - shown.length;
+    return (`No result in the scope has ${shown.join(', ')}${more > 0 ? ` and ${more} more` : ''}, so ` +
+        `${missing.length === 1 ? 'it reads' : 'they read'} as NULL — op "describe" lists the paths the results have.`);
+}