@3minapi/cli 0.0.0-stage → 0.22.1

package/dist/modules/workers/results/shape.js

@@ -0,0 +1,212 @@
+import { createHash } from 'node:crypto';
+import { SHAPE_MAX_DEPTH, SHAPE_MAX_PATHS, SHAPE_PATH_MAX_CHARS, SHAPE_MAX_VALUES, SHAPE_VALUE_MAX_CHARS } from "../../../core/domain/index.js";
+const IDENT = /^[A-Za-z_][A-Za-z0-9_]*$/;
+export function computeShape(value) {
+    const acc = new Map();
+    let truncated = false;
+    const visit = (v, path, depth) => {
+        let a = acc.get(path);
+        if (!a) {
+            if (acc.size >= SHAPE_MAX_PATHS || path.length > SHAPE_PATH_MAX_CHARS) {
+                truncated = true;
+                return;
+            }
+            a = { stat: { types: {}, count: 0 }, values: new Set() };
+            acc.set(path, a);
+        }
+        const { stat } = a;
+        const type = jsonType(v);
+        stat.types[type] = (stat.types[type] ?? 0) + 1;
+        stat.count++;
+        switch (type) {
+            case 'integer':
+            case 'real': {
+                const n = v;
+                stat.min = stat.min === undefined ? n : Math.min(stat.min, n);
+                stat.max = stat.max === undefined ? n : Math.max(stat.max, n);
+                return;
+            }
+            case 'text': {
+                const t = v;
+                if (a.values && (t.length > SHAPE_VALUE_MAX_CHARS || a.values.size >= SHAPE_MAX_VALUES)) {
+                    if (!a.values.has(t)) {
+                        stat.sample = (a.values.values().next().value ?? t).slice(0, SHAPE_VALUE_MAX_CHARS);
+                        a.values = null;
+                    }
+                }
+                if (a.values)
+                    a.values.add(t);
+                else
+                    stat.sample ??= t.slice(0, SHAPE_VALUE_MAX_CHARS);
+                return;
+            }
+            case 'array': {
+                const arr = v;
+                stat.length = stat.length
+                    ? {
+                        min: Math.min(stat.length.min, arr.length),
+                        max: Math.max(stat.length.max, arr.length)
+                    }
+                    : { min: arr.length, max: arr.length };
+                if (depth >= SHAPE_MAX_DEPTH) {
+                    if (arr.length > 0)
+                        truncated = true;
+                    return;
+                }
+                for (const item of arr)
+                    visit(item, `${path}[*]`, depth + 1);
+                return;
+            }
+            case 'object': {
+                const entries = Object.entries(v);
+                if (depth >= SHAPE_MAX_DEPTH) {
+                    if (entries.length > 0)
+                        truncated = true;
+                    return;
+                }
+                for (const [key, child] of entries)
+                    visit(child, childPath(path, key), depth + 1);
+                return;
+            }
+            default:
+                return;
+        }
+    };
+    visit(value, '$', 0);
+    const paths = {};
+    for (const [path, a] of acc) {
+        if (a.values && a.values.size > 0) {
+            a.stat.values = [...a.values].sort();
+            delete a.stat.sample;
+        }
+        paths[path] = a.stat;
+    }
+    const shape = { v: 1, paths, truncated };
+    return { shape, hash: shapeHash(shape) };
+}
+export class ShapeMerger {
+    acc = new Map();
+    truncated = false;
+    add(shape) {
+        if (shape.truncated)
+            this.truncated = true;
+        for (const [path, s] of Object.entries(shape.paths)) {
+            let a = this.acc.get(path);
+            if (!a) {
+                a = { stat: { types: {}, count: 0 }, values: new Set() };
+                this.acc.set(path, a);
+            }
+            const { stat } = a;
+            for (const [type, n] of Object.entries(s.types)) {
+                stat.types[type] = (stat.types[type] ?? 0) + n;
+            }
+            stat.count += s.count;
+            if (s.min !== undefined)
+                stat.min = stat.min === undefined ? s.min : Math.min(stat.min, s.min);
+            if (s.max !== undefined)
+                stat.max = stat.max === undefined ? s.max : Math.max(stat.max, s.max);
+            if (s.length) {
+                stat.length = stat.length
+                    ? {
+                        min: Math.min(stat.length.min, s.length.min),
+                        max: Math.max(stat.length.max, s.length.max)
+                    }
+                    : { ...s.length };
+            }
+            if (!a.values)
+                continue;
+            const first = a.values.values().next().value ?? s.values?.[0] ?? s.sample;
+            if (s.sample !== undefined) {
+                stat.sample = first;
+                a.values = null;
+                continue;
+            }
+            for (const v of s.values ?? [])
+                a.values.add(v);
+            if (a.values.size > SHAPE_MAX_VALUES) {
+                stat.sample = first;
+                a.values = null;
+            }
+        }
+    }
+    result() {
+        const paths = {};
+        for (const [path, a] of this.acc) {
+            if (a.values && a.values.size > 0)
+                a.stat.values = [...a.values].sort();
+            paths[path] = a.stat;
+        }
+        return { v: 1, paths, truncated: this.truncated };
+    }
+}
+export function fitShape(shape, fits) {
+    if (fits(shape))
+        return shape;
+    const entries = Object.entries(shape.paths).map(([p, stat]) => ({
+        p,
+        stat,
+        depth: pathDepth(p)
+    }));
+    const maxDepth = Math.max(0, ...entries.map((e) => e.depth));
+    const build = (samplesFrom, pathsFrom) => ({
+        v: 1,
+        paths: Object.fromEntries(entries
+            .filter((e) => e.depth < pathsFrom)
+            .map(({ p, stat, depth }) => {
+            if (depth < samplesFrom)
+                return [p, stat];
+            const { values: _values, sample: _sample, ...rest } = stat;
+            return [p, rest];
+        })),
+        truncated: true,
+        omitted: {
+            ...(samplesFrom <= maxDepth ? { samples_from_depth: samplesFrom } : {}),
+            ...(pathsFrom <= maxDepth ? { paths_from_depth: pathsFrom } : {})
+        }
+    });
+    let pathsFrom = maxDepth + 1;
+    for (let d = maxDepth; d >= 0; d--) {
+        const stripped = build(d, pathsFrom);
+        if (fits(stripped))
+            return stripped;
+        pathsFrom = d;
+        const dropped = build(d, pathsFrom);
+        if (fits(dropped))
+            return dropped;
+    }
+    return {
+        v: 1,
+        paths: {},
+        truncated: true,
+        omitted: { samples_from_depth: 0, paths_from_depth: 0 }
+    };
+}
+export function pathDepth(path) {
+    return (path.match(/\[\*\]|\.(?:"(?:[^"\\]|\\.)*"|[A-Za-z_][A-Za-z0-9_]*)/g) ?? []).length;
+}
+export function shapeHash(shape) {
+    const canonical = Object.keys(shape.paths)
+        .sort()
+        .map((p) => `${p}=${Object.keys(shape.paths[p].types).sort().join('|')}`)
+        .join('\n');
+    return createHash('sha256').update(`v${shape.v}\n${canonical}`).digest('hex').slice(0, 16);
+}
+export function childPath(parent, key) {
+    return IDENT.test(key) ? `${parent}.${key}` : `${parent}.${JSON.stringify(key)}`;
+}
+function jsonType(v) {
+    if (v === null)
+        return 'null';
+    if (Array.isArray(v))
+        return 'array';
+    switch (typeof v) {
+        case 'string':
+            return 'text';
+        case 'number':
+            return Number.isInteger(v) ? 'integer' : 'real';
+        case 'boolean':
+            return v ? 'true' : 'false';
+        default:
+            return 'object';
+    }
+}

package/dist/modules/workers/results/store.js

@@ -0,0 +1,336 @@
+import { existsSync, statSync } from 'node:fs';
+import path from 'node:path';
+import { DatabaseSync } from 'node:sqlite';
+import { BIN, CliError, ConfigError, DB_BUSY_TIMEOUT_MS, RESULTS_META_TABLE, RESULTS_SCHEMA_VERSION, RESULTS_TABLE, USER_DB_FILE } from "../../../core/domain/index.js";
+import { touchSecretFile } from "../../../core/secure-fs.js";
+const RESULTS_COLUMNS = `	task_id TEXT NOT NULL,
+	worker TEXT NOT NULL,
+	created_at TEXT NOT NULL,
+	source TEXT NOT NULL,
+	status TEXT NOT NULL,
+	reply TEXT NOT NULL,
+	bytes INTEGER NOT NULL,
+	shape_hash TEXT,
+	shape TEXT,
+	host_id TEXT,
+	run_no INTEGER NOT NULL DEFAULT 1,
+	payload TEXT NOT NULL,
+	PRIMARY KEY (task_id, run_no)`;
+const SCHEMA = `
+CREATE TABLE IF NOT EXISTS ${RESULTS_TABLE} (
+${RESULTS_COLUMNS}
+) STRICT;
+CREATE INDEX IF NOT EXISTS ${RESULTS_TABLE}_worker ON ${RESULTS_TABLE}(worker, created_at);
+CREATE INDEX IF NOT EXISTS ${RESULTS_TABLE}_host ON ${RESULTS_TABLE}(host_id, worker, created_at);
+CREATE INDEX IF NOT EXISTS ${RESULTS_TABLE}_created ON ${RESULTS_TABLE}(created_at);
+CREATE TABLE IF NOT EXISTS ${RESULTS_META_TABLE} (key TEXT PRIMARY KEY, value TEXT NOT NULL) STRICT;
+`;
+const ROW_COLUMNS = 'task_id, worker, created_at, source, status, reply, bytes, shape_hash, host_id, run_no';
+const LATEST = `SELECT ${ROW_COLUMNS}, shape, payload FROM ${RESULTS_TABLE} WHERE task_id = ? ORDER BY run_no DESC LIMIT 1`;
+export function resultsDbPath(root) {
+    return path.join(root, USER_DB_FILE);
+}
+export function resultsDbBytes(root) {
+    const file = resultsDbPath(root);
+    if (!existsSync(file))
+        return null;
+    const wal = `${file}-wal`;
+    return statSync(file).size + (existsSync(wal) ? statSync(wal).size : 0);
+}
+export class ResultStore {
+    db;
+    hostId = null;
+    constructor(db) {
+        this.db = db;
+    }
+    static open(root) {
+        const file = resultsDbPath(root);
+        if (!existsSync(file))
+            touchSecretFile(file);
+        const db = new DatabaseSync(file, { timeout: DB_BUSY_TIMEOUT_MS });
+        try {
+            const warnings = ensureWal(db);
+            migrate(db);
+            return { store: new ResultStore(db), warnings };
+        }
+        catch (err) {
+            if (db.isOpen)
+                db.close();
+            throw err;
+        }
+    }
+    static openReadOnly(root) {
+        const file = resultsDbPath(root);
+        if (!existsSync(file))
+            return null;
+        let db;
+        try {
+            db = new DatabaseSync(file, { readOnly: true, timeout: DB_BUSY_TIMEOUT_MS });
+            if (!hasTable(db, RESULTS_TABLE)) {
+                db.close();
+                return null;
+            }
+            if (!hasColumn(db, RESULTS_TABLE, 'run_no')) {
+                throw new ConfigError(`the result table in ${file} was made by an older 3minapi — run '${BIN} start' or '${BIN} worker results' once to upgrade it`);
+            }
+            const schema = hasTable(db, RESULTS_META_TABLE)
+                ? db.prepare(`SELECT value FROM ${RESULTS_META_TABLE} WHERE key = 'schema'`).get()?.value
+                : undefined;
+            if (schema !== undefined && Number(schema) > RESULTS_SCHEMA_VERSION) {
+                throw new ConfigError(`the result tables in ${file} were made by a newer 3minapi (schema ${schema}) — update the CLI`);
+            }
+            return new ResultStore(db);
+        }
+        catch (err) {
+            if (db?.isOpen)
+                db.close();
+            if (err instanceof CliError)
+                throw err;
+            throw new CliError(`cannot open ${file}: ${err?.message ?? String(err)}`);
+        }
+    }
+    setHost(hostId) {
+        this.hostId = hostId;
+    }
+    save(rec) {
+        this.db
+            .prepare(`INSERT INTO ${RESULTS_TABLE} (task_id, worker, created_at, source, status, reply, bytes, shape_hash, shape, payload, host_id, run_no)
+				 VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+				 ON CONFLICT(task_id, run_no) DO UPDATE SET
+				   worker = excluded.worker, created_at = excluded.created_at, source = excluded.source,
+				   status = excluded.status, reply = excluded.reply, bytes = excluded.bytes,
+				   shape_hash = excluded.shape_hash, shape = excluded.shape, payload = excluded.payload,
+				   host_id = excluded.host_id`)
+            .run(rec.taskId, rec.worker, new Date(rec.createdAt).toISOString(), rec.source, rec.status, rec.reply, Buffer.byteLength(rec.payload), rec.shapeHash, rec.shape === null ? null : JSON.stringify(rec.shape), rec.payload, this.hostId, rec.runNo ?? 1);
+    }
+    setReply(taskId, reply, runNo = 1) {
+        this.db
+            .prepare(`UPDATE ${RESULTS_TABLE} SET reply = ? WHERE task_id = ? AND run_no = ?`)
+            .run(reply, taskId, runNo);
+    }
+    list(filter, limit) {
+        const { where, params } = whereClause(filter);
+        return this.db
+            .prepare(`SELECT ${ROW_COLUMNS} FROM ${RESULTS_TABLE} ${where} ORDER BY created_at DESC, task_id LIMIT ?`)
+            .all(...params, limit);
+    }
+    rowsByIds(ids) {
+        if (ids.length === 0)
+            return [];
+        return this.db
+            .prepare(`SELECT ${ROW_COLUMNS} FROM ${RESULTS_TABLE} r WHERE task_id IN (${ids.map(() => '?').join(', ')})
+				   AND run_no = (SELECT max(run_no) FROM ${RESULTS_TABLE} WHERE task_id = r.task_id)`)
+            .all(...ids);
+    }
+    get(taskId, runNo) {
+        const row = (runNo === undefined
+            ? this.db.prepare(LATEST).get(taskId)
+            : this.db
+                .prepare(`SELECT ${ROW_COLUMNS}, shape, payload FROM ${RESULTS_TABLE} WHERE task_id = ? AND run_no = ?`)
+                .get(taskId, runNo));
+        return row ? stored(row) : null;
+    }
+    runs(taskId, limit, before) {
+        return this.db
+            .prepare(`SELECT ${ROW_COLUMNS} FROM ${RESULTS_TABLE} WHERE task_id = ?${before === undefined ? '' : ' AND run_no < ?'}
+				 ORDER BY run_no DESC LIMIT ?`)
+            .all(...(before === undefined ? [taskId, limit] : [taskId, before, limit]));
+    }
+    runPreviews(taskId, limit, before, maxBytes) {
+        return this.db
+            .prepare(`SELECT ${ROW_COLUMNS}, CASE WHEN bytes <= ? THEN payload END AS payload FROM ${RESULTS_TABLE}
+				 WHERE task_id = ?${before === undefined ? '' : ' AND run_no < ?'} ORDER BY run_no DESC LIMIT ?`)
+            .all(...(before === undefined ? [maxBytes, taskId, limit] : [maxBytes, taskId, before, limit]));
+    }
+    nextRunNo(taskId, runNo) {
+        const row = this.db
+            .prepare(`SELECT min(run_no) AS n FROM ${RESULTS_TABLE} WHERE task_id = ? AND run_no > ?`)
+            .get(taskId, runNo);
+        return row?.n ?? null;
+    }
+    runCounts(ids) {
+        const out = new Map();
+        if (ids.length === 0)
+            return out;
+        const rows = this.db
+            .prepare(`SELECT task_id, count(*) AS runs, max(run_no) AS last FROM ${RESULTS_TABLE}
+				 WHERE task_id IN (${ids.map(() => '?').join(', ')}) GROUP BY task_id`)
+            .all(...ids);
+        for (const r of rows)
+            out.set(r.task_id, { runs: Number(r.runs), lastRunNo: Number(r.last) });
+        return out;
+    }
+    find(idOrPrefix) {
+        const exact = this.db.prepare(LATEST).get(idOrPrefix);
+        if (exact)
+            return { found: stored(exact) };
+        const ids = this.db
+            .prepare(`SELECT DISTINCT task_id FROM ${RESULTS_TABLE} WHERE task_id >= ? AND task_id < ? ORDER BY task_id LIMIT 6`)
+            .all(idOrPrefix, `${idOrPrefix}\uffff`);
+        if (ids.length === 1) {
+            const row = this.db.prepare(LATEST).get(ids[0].task_id);
+            return { found: stored(row) };
+        }
+        return { candidates: ids.map((r) => r.task_id) };
+    }
+    snapshot(read) {
+        this.db.exec('BEGIN');
+        try {
+            return read();
+        }
+        finally {
+            this.db.exec('COMMIT');
+        }
+    }
+    shapeGroups(filter) {
+        const { where, params } = shapeWhere(filter);
+        return this.db
+            .prepare(`SELECT shape_hash, count(*) AS count, min(created_at) AS first, max(created_at) AS last
+				 FROM ${RESULTS_TABLE} ${where} GROUP BY shape_hash ORDER BY count DESC, first, shape_hash`)
+            .all(...params);
+    }
+    latestShapeHash(filter) {
+        const { where, params } = shapeWhere(filter);
+        const row = this.db
+            .prepare(`SELECT shape_hash FROM ${RESULTS_TABLE} ${where} ORDER BY created_at DESC, task_id DESC LIMIT 1`)
+            .get(...params);
+        return row?.shape_hash ?? null;
+    }
+    recentTaskIds(filter, shapeHash, limit) {
+        const { where, params } = shapeWhere(filter, shapeHash);
+        return this.db
+            .prepare(`SELECT task_id FROM ${RESULTS_TABLE} ${where}
+					 GROUP BY task_id ORDER BY max(created_at) DESC, task_id DESC LIMIT ?`)
+            .all(...params, limit).map((r) => r.task_id);
+    }
+    recentShapes(filter, shapeHash, limit) {
+        const { where, params } = shapeWhere(filter, shapeHash);
+        return this.db
+            .prepare(`SELECT created_at, shape FROM (
+				   SELECT created_at, task_id, shape FROM ${RESULTS_TABLE} ${where}
+				   ORDER BY created_at DESC, task_id DESC LIMIT ?
+				 ) ORDER BY created_at, task_id`)
+            .iterate(...params, limit);
+    }
+    usage(filter = {}) {
+        const { where, params } = whereClause(filter);
+        const row = this.db
+            .prepare(`SELECT count(*) AS count, coalesce(sum(bytes), 0) AS bytes FROM ${RESULTS_TABLE} ${where}`)
+            .get(...params);
+        return { count: row.count, bytes: row.bytes };
+    }
+    prune(filter) {
+        const { where, params } = whereClause(filter);
+        return Number(this.db.prepare(`DELETE FROM ${RESULTS_TABLE} ${where}`).run(...params).changes);
+    }
+    close() {
+        if (this.db.isOpen)
+            this.db.close();
+    }
+}
+function stored(raw) {
+    return { ...raw, shape: raw.shape === null ? null : JSON.parse(raw.shape) };
+}
+function whereClause(filter, extra = []) {
+    const conds = [...extra];
+    const params = [];
+    if (filter.worker !== undefined) {
+        conds.push('worker = ?');
+        params.push(filter.worker);
+    }
+    if (filter.since !== undefined) {
+        conds.push('created_at >= ?');
+        params.push(filter.since);
+    }
+    if (filter.before !== undefined) {
+        conds.push('created_at < ?');
+        params.push(filter.before);
+    }
+    if (filter.hostId !== undefined) {
+        conds.push('host_id = ?');
+        params.push(filter.hostId);
+    }
+    if (filter.status !== undefined) {
+        conds.push('status = ?');
+        params.push(filter.status);
+    }
+    if (filter.after !== undefined) {
+        conds.push('created_at <= ? AND (created_at < ? OR task_id > ?)');
+        params.push(filter.after.createdAt, filter.after.createdAt, filter.after.taskId);
+    }
+    if (filter.sources !== undefined) {
+        conds.push(`source IN (${filter.sources.map(() => '?').join(', ') || 'NULL'})`);
+        params.push(...filter.sources);
+    }
+    if (filter.latestRunOnly) {
+        conds.push(`run_no = (SELECT max(x.run_no) FROM ${RESULTS_TABLE} x WHERE x.task_id = ${RESULTS_TABLE}.task_id)`);
+    }
+    return { where: conds.length > 0 ? `WHERE ${conds.join(' AND ')}` : '', params };
+}
+function shapeWhere(filter, shapeHash) {
+    const { where, params } = whereClause(filter, [
+        "status = 'completed'",
+        shapeHash === undefined ? 'shape_hash IS NOT NULL' : 'shape_hash = ?'
+    ]);
+    return { where, params: shapeHash === undefined ? params : [shapeHash, ...params] };
+}
+function hasTable(db, name) {
+    return (db.prepare(`SELECT 1 FROM sqlite_schema WHERE type = 'table' AND name = ?`).get(name) !==
+        undefined);
+}
+function ensureWal(db) {
+    const mode = db.prepare('PRAGMA journal_mode').get().journal_mode;
+    if (mode === 'wal')
+        return [];
+    try {
+        const now = db.prepare('PRAGMA journal_mode = WAL').get()
+            .journal_mode;
+        return now === 'wal' ? [] : [`data.db stays in ${now} journal mode (could not switch to WAL)`];
+    }
+    catch (err) {
+        return [`data.db could not switch to WAL: ${err.message}`];
+    }
+}
+function migrate(db) {
+    db.exec('BEGIN IMMEDIATE');
+    try {
+        if (hasTable(db, RESULTS_TABLE) && !hasColumn(db, RESULTS_TABLE, 'run_no'))
+            rebuildWithRunNo(db);
+        db.exec(SCHEMA);
+        const row = db.prepare(`SELECT value FROM ${RESULTS_META_TABLE} WHERE key = 'schema'`).get();
+        if (row === undefined) {
+            db.prepare(`INSERT INTO ${RESULTS_META_TABLE} (key, value) VALUES ('schema', ?)`).run(String(RESULTS_SCHEMA_VERSION));
+        }
+        else if (Number(row.value) > RESULTS_SCHEMA_VERSION) {
+            throw new Error(`the result tables in data.db were made by a newer 3minapi (schema ${row.value}) — update the CLI`);
+        }
+        db.exec('COMMIT');
+    }
+    catch (err) {
+        if (db.isTransaction)
+            db.exec('ROLLBACK');
+        throw err;
+    }
+}
+function hasColumn(db, table, column) {
+    return db.prepare(`PRAGMA table_info(${table})`).all().some((c) => c.name === column);
+}
+function rebuildWithRunNo(db) {
+    const tmp = `${RESULTS_TABLE}_rebuild`;
+    const objects = db
+        .prepare(`SELECT type, name, sql FROM sqlite_schema
+			 WHERE sql IS NOT NULL AND name NOT LIKE 'sqlite_%'
+			   AND ((type IN ('index', 'trigger') AND tbl_name = ?) OR (type = 'view' AND instr(sql, ?) > 0))`)
+        .all(RESULTS_TABLE, RESULTS_TABLE);
+    for (const v of objects.filter((o) => o.type === 'view'))
+        db.exec(`DROP VIEW "${v.name.replaceAll('"', '""')}"`);
+    db.exec(`CREATE TABLE ${tmp} (\n${RESULTS_COLUMNS}\n) STRICT`);
+    db.exec(`INSERT INTO ${tmp} (task_id, worker, created_at, source, status, reply, bytes, shape_hash, shape, host_id, run_no, payload)
+		 SELECT task_id, worker, created_at, source, status, reply, bytes, shape_hash, shape, host_id, 1, payload FROM ${RESULTS_TABLE}`);
+    db.exec(`DROP TABLE ${RESULTS_TABLE}`);
+    db.exec(`ALTER TABLE ${tmp} RENAME TO ${RESULTS_TABLE}`);
+    for (const type of ['index', 'trigger', 'view']) {
+        for (const o of objects.filter((x) => x.type === type))
+            db.exec(o.sql);
+    }
+}

package/dist/modules/workers/results/substitute.js

@@ -0,0 +1,30 @@
+import { RESULT_RESERVED_KEY, SUBSTITUTE_MAX_BYTES } from "../../../core/domain/index.js";
+import { formatCount } from "../../../core/text.js";
+import { fitShape } from "./shape.js";
+export const SUBSTITUTE_READ = "The full result is too large to send and is stored on the user's PC. Do not present this summary as the result. " +
+    '`shape` summarizes its structure: the paths it has, with types, counts and sample values — an overview; ' +
+    'deeper levels may be left out (`omitted`), and {"op":"describe","task_id":"<task_id>"} returns them. ' +
+    'Compute the answer over those paths by creating a task for the worker in `reader` with input ' +
+    '{"op":"query","task_id":"<task_id>","sql":"SELECT … FROM results"} — help(tasks) explains the view and examples.';
+export const SUBSTITUTE_READ_LOCAL_ONLY = "The full result is too large to send and is stored on the user's PC. The user can see it with " +
+    "'3minapi worker results show <task_id>' or query it with '3minapi worker results query'. " +
+    '`shape` summarizes its structure: paths, types, counts and sample values — an overview; deeper ' +
+    'levels may be left out (`omitted`).';
+export function substituteResult(input) {
+    const build = (shape) => ({
+        [RESULT_RESERVED_KEY]: {
+            stored_locally: true,
+            task_id: input.taskId,
+            worker: input.worker,
+            bytes: input.bytes,
+            shape_hash: input.shapeHash,
+            shape,
+            ...(input.reader ? { reader: input.reader } : {}),
+            read: input.reader ? SUBSTITUTE_READ : SUBSTITUTE_READ_LOCAL_ONLY
+        }
+    });
+    return build(fitShape(input.shape, (s) => Buffer.byteLength(JSON.stringify(build(s))) <= SUBSTITUTE_MAX_BYTES));
+}
+export function substituteStatusMessage(bytes) {
+    return `result stored on the user's PC (${formatCount(bytes)} bytes)`;
+}

package/dist/modules/workers/runtime/env.js

@@ -0,0 +1,43 @@
+import { statSync } from 'node:fs';
+import path from 'node:path';
+import { parseEnv } from 'node:util';
+import { CLI_ENV_PREFIX, ConfigError } from "../../../core/domain/index.js";
+import { readUserText } from "../../../core/text-file.js";
+export const DOTENV_FILE = '.env';
+const cache = new Map();
+export function readDotEnv(projectRoot) {
+    const file = path.join(projectRoot, DOTENV_FILE);
+    let text;
+    try {
+        const stat = statSync(file, { throwIfNoEntry: false });
+        if (!stat) {
+            cache.delete(file);
+            return {};
+        }
+        const hit = cache.get(file);
+        if (hit && hit.mtimeMs === stat.mtimeMs && hit.size === stat.size)
+            return { ...hit.values };
+        text = readUserText(file);
+        const values = parseEnv(text);
+        cache.set(file, { mtimeMs: stat.mtimeMs, size: stat.size, values });
+        return { ...values };
+    }
+    catch (err) {
+        if (err instanceof ConfigError)
+            throw err;
+        if (err.code === 'ENOENT')
+            return {};
+        throw new ConfigError(`cannot read ${file}: ${err.message}`);
+    }
+}
+export function workerEnv(projectRoot, base) {
+    const merged = { ...base, ...readDotEnv(projectRoot) };
+    for (const key of Object.keys(merged)) {
+        if (key.startsWith(CLI_ENV_PREFIX))
+            delete merged[key];
+    }
+    return merged;
+}
+export function publicKeyEnv(projectRoot, base) {
+    return { ...readDotEnv(projectRoot), ...base };
+}