@alisio/core 0.1.0-alpha.20 → 0.1.0-alpha.22

package/dist/analysis/data/json.js

@@ -0,0 +1,44 @@
+/**
+ * JSON and JSON Lines helpers of the dataset ingestion (spec §17.2). Pure: the ingestion engine
+ * feeds decoded text and gets records back. Nested values are stored as JSON text by the caller.
+ */
+/** Splits streamed text into lines (`\n` or `\r\n`); the last partial line waits for more text. */
+export class LineSplitter {
+    onLine;
+    rest = "";
+    constructor(onLine) {
+        this.onLine = onLine;
+    }
+    write(chunk) {
+        const text = this.rest + chunk;
+        let start = 0;
+        for (;;) {
+            const end = text.indexOf("\n", start);
+            if (end < 0)
+                break;
+            const stop = end > start && text.charCodeAt(end - 1) === 13 ? end - 1 : end;
+            this.onLine(text.slice(start, stop));
+            start = end + 1;
+        }
+        this.rest = start === 0 ? text : text.slice(start);
+    }
+    end() {
+        if (this.rest)
+            this.onLine(this.rest.endsWith("\r") ? this.rest.slice(0, -1) : this.rest);
+        this.rest = "";
+    }
+}
+/** A plain object stays as it is; any other JSON value becomes `{ value }`. */
+export function toRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : { value };
+}
+/**
+ * The records of a JSON document: an array (each element a record) or a single object (one
+ * record). Throws a `SyntaxError` for invalid JSON.
+ */
+export function jsonDocumentRecords(text) {
+    const parsed = JSON.parse(text);
+    return Array.isArray(parsed) ? parsed.map(toRecord) : [toRecord(parsed)];
+}

package/dist/analysis/data/query-worker.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Query side of the data engine (spec §17.3): runs one read-only statement on a dataset file.
+ * The connection is opened `readOnly`, then `query_only=ON` and `trusted_schema=OFF`; extension
+ * loading stays disabled (the `node:sqlite` default). The host kills the process when a statement
+ * exceeds its time limit: `node:sqlite` offers no interrupt, progress handler or authorizer.
+ */
+import type { QueryRequest, QueryResult } from "./engine-types.ts";
+/** Closes one connection (or all of them): the host does this before deleting a file. */
+export declare function closeConnections(path?: string): void;
+export declare class QueryRejected extends Error {
+}
+export declare function runQuery(req: QueryRequest): QueryResult;

package/dist/analysis/data/query-worker.js

@@ -0,0 +1,75 @@
+import { guardSql } from "./sql-guard.js";
+const sqlite = process.getBuiltinModule("node:sqlite");
+const connections = new Map();
+function connect(path, heapBytes) {
+    let db = connections.get(path);
+    if (!db) {
+        db = new sqlite.DatabaseSync(path, { readOnly: true });
+        db.exec("PRAGMA query_only=ON; PRAGMA trusted_schema=OFF;");
+        if (heapBytes)
+            db.exec(`PRAGMA hard_heap_limit=${Math.floor(heapBytes)};`);
+        connections.set(path, db);
+    }
+    return db;
+}
+/** Closes one connection (or all of them): the host does this before deleting a file. */
+export function closeConnections(path) {
+    for (const [key, db] of connections) {
+        if (path && key !== path)
+            continue;
+        try {
+            db.close();
+        }
+        catch {
+            /* already closed */
+        }
+        connections.delete(key);
+    }
+}
+export class QueryRejected extends Error {
+}
+export function runQuery(req) {
+    let sql = req.sql;
+    if (req.guard) {
+        const guarded = guardSql(sql);
+        if (!guarded.ok)
+            throw new QueryRejected(guarded.reason);
+        sql = guarded.sql;
+    }
+    const db = connect(req.db, req.heapBytes);
+    const statement = db.prepare(sql);
+    statement.setReadBigInts(true);
+    statement.setReturnArrays(true);
+    const columns = statement.columns().map((c) => c.name);
+    const rows = [];
+    let truncated = false;
+    let clipped = false;
+    const cell = (value) => {
+        if (value === null || value === undefined)
+            return null;
+        if (typeof value === "bigint") {
+            const n = Number(value);
+            return Number.isSafeInteger(n) ? n : value.toString();
+        }
+        if (typeof value === "number")
+            return value;
+        if (value instanceof Uint8Array)
+            return `<blob ${value.byteLength} bytes>`;
+        const text = String(value);
+        if (text.length > req.cellChars) {
+            clipped = true;
+            return `${text.slice(0, req.cellChars)}…`;
+        }
+        return text;
+    };
+    // JS numbers bind as REAL, which `LIMIT`/`OFFSET` reject: integral values bind as INTEGER.
+    const bound = (req.params ?? []).map((value) => typeof value === "number" && Number.isSafeInteger(value) ? BigInt(value) : value);
+    for (const row of statement.iterate(...bound)) {
+        if (rows.length >= req.maxRows) {
+            truncated = true;
+            break;
+        }
+        rows.push(row.map(cell));
+    }
+    return { columns, rows, truncated, clipped };
+}

package/dist/analysis/data/rows.d.ts

@@ -0,0 +1,39 @@
+export declare const MAX_PAGE_ROWS = 500;
+export declare const MAX_OFFSET = 100000;
+/** Filtering every column at once (no `column`) is only allowed up to this many rows. */
+export declare const MAX_ALL_COLUMNS_FILTER_ROWS = 100000;
+export interface PageParams {
+    table: string;
+    columns: string[];
+    limit: number;
+    sort?: {
+        column: string;
+        dir: "asc" | "desc";
+    };
+    /** Substring filter on one column (or on every column when `column` is absent). */
+    filter?: {
+        column?: string;
+        text: string;
+    };
+    /** Opaque cursor returned by the previous page. */
+    after?: string;
+    /** Rows to skip (jump). */
+    offset?: number;
+}
+export declare class PageParamError extends Error {
+}
+/** The cursor of a row: base64 of `[rowid]`. */
+export declare const encodeCursor: (rowid: number) => string;
+export declare function decodeCursor(cursor: string): number;
+type Param = string | number | null;
+/** Statement and parameters of one page (`limit + 1` rows, to know whether a next page exists). */
+export declare function buildPageQuery(params: PageParams): {
+    sql: string;
+    params: Param[];
+};
+/** `SELECT count(*)` of the filter (shown on the first page of a filtered view). */
+export declare function buildCountQuery(params: Pick<PageParams, "table" | "columns" | "filter">): {
+    sql: string;
+    params: Param[];
+};
+export {};

package/dist/analysis/data/rows.js

@@ -0,0 +1,120 @@
+/**
+ * SQL of `SpreadsheetView` pages (spec §17.4). Pure: builds trusted statements for the engine.
+ * Paging is keyset-based on `rowid` (dense, in file order), so a page never scans from the start
+ * for the unsorted view and never duplicates or skips rows while sorting. `LIMIT/OFFSET` only
+ * serves jumps to a position when a sort or filter is active (≤ 100 000 rows in).
+ */
+import { quoteIdent } from "./infer.js";
+export const MAX_PAGE_ROWS = 500;
+export const MAX_OFFSET = 100_000;
+/** Filtering every column at once (no `column`) is only allowed up to this many rows. */
+export const MAX_ALL_COLUMNS_FILTER_ROWS = 100_000;
+export class PageParamError extends Error {
+}
+/** The cursor of a row: base64 of `[rowid]`. */
+export const encodeCursor = (rowid) => Buffer.from(JSON.stringify([rowid])).toString("base64url");
+export function decodeCursor(cursor) {
+    try {
+        const value = JSON.parse(Buffer.from(cursor, "base64url").toString("utf8"));
+        if (Array.isArray(value) && Number.isSafeInteger(value[0]) && value[0] >= 0)
+            return value[0];
+    }
+    catch {
+        /* falls through */
+    }
+    throw new PageParamError("Invalid cursor");
+}
+const escapeLike = (text) => text.replace(/[\\%_]/g, (c) => `\\${c}`);
+/** Statement and parameters of one page (`limit + 1` rows, to know whether a next page exists). */
+export function buildPageQuery(params) {
+    const table = quoteIdent(params.table);
+    const known = new Set(params.columns);
+    const values = [];
+    const where = [];
+    const sortColumn = params.sort?.column;
+    if (sortColumn !== undefined && !known.has(sortColumn))
+        throw new PageParamError(`Unknown column: ${sortColumn}`);
+    if (params.filter?.text) {
+        const like = `%${escapeLike(params.filter.text)}%`;
+        if (params.filter.column !== undefined) {
+            if (!known.has(params.filter.column))
+                throw new PageParamError(`Unknown column: ${params.filter.column}`);
+            where.push(`${quoteIdent(params.filter.column)} LIKE ? ESCAPE '\\'`);
+            values.push(like);
+        }
+        else {
+            where.push(`(${params.columns.map((c) => `${quoteIdent(c)} LIKE ? ESCAPE '\\'`).join(" OR ")})`);
+            for (let i = 0; i < params.columns.length; i++)
+                values.push(like);
+        }
+    }
+    const filtered = where.length > 0;
+    let order = "rowid";
+    let offset = 0;
+    if (sortColumn === undefined) {
+        if (params.after) {
+            where.push("rowid > ?");
+            values.push(decodeCursor(params.after));
+        }
+        else if (params.offset) {
+            if (!filtered) {
+                // rowid is dense (1..N in file order): jumping needs no OFFSET at all.
+                where.push("rowid > ?");
+                values.push(params.offset);
+            }
+            else
+                offset = params.offset;
+        }
+    }
+    else {
+        const k = quoteIdent(sortColumn);
+        const asc = params.sort?.dir !== "desc";
+        order = `${k} ${asc ? "ASC" : "DESC"}, rowid ASC`;
+        if (params.after) {
+            const r = decodeCursor(params.after);
+            const v = `(SELECT ${k} FROM ${table} WHERE rowid = ?)`;
+            // NULLs sort first ascending and last descending; ties break on rowid ascending.
+            const next = asc
+                ? `((${v} IS NULL AND (${k} IS NOT NULL OR rowid > ?)) OR ` +
+                    `(${v} IS NOT NULL AND (${k} > ${v} OR (${k} = ${v} AND rowid > ?))))`
+                : `((${v} IS NULL AND ${k} IS NULL AND rowid > ?) OR ` +
+                    `(${v} IS NOT NULL AND (${k} < ${v} OR (${k} = ${v} AND rowid > ?) OR ${k} IS NULL)))`;
+            where.push(next);
+            for (let i = 0; i < 6; i++)
+                values.push(r);
+        }
+        else if (params.offset)
+            offset = params.offset;
+    }
+    if (offset > MAX_OFFSET)
+        throw new PageParamError(`Jumping is limited to the first ${MAX_OFFSET} rows when sorting or filtering`);
+    const select = ["rowid", ...params.columns.map(quoteIdent)].join(", ");
+    values.push(Math.min(params.limit, MAX_PAGE_ROWS) + 1);
+    const sql = `SELECT ${select} FROM ${table}` +
+        (where.length ? ` WHERE ${where.join(" AND ")}` : "") +
+        ` ORDER BY ${order} LIMIT ?` +
+        (offset ? ` OFFSET ${Math.floor(offset)}` : "");
+    return { sql, params: values };
+}
+/** `SELECT count(*)` of the filter (shown on the first page of a filtered view). */
+export function buildCountQuery(params) {
+    const table = quoteIdent(params.table);
+    const text = params.filter?.text;
+    if (!text)
+        return { sql: `SELECT count(*) FROM ${table}`, params: [] };
+    const like = `%${escapeLike(text)}%`;
+    if (params.filter?.column !== undefined) {
+        if (!params.columns.includes(params.filter.column))
+            throw new PageParamError(`Unknown column: ${params.filter.column}`);
+        return {
+            sql: `SELECT count(*) FROM ${table} WHERE ${quoteIdent(params.filter.column)} LIKE ? ESCAPE '\\'`,
+            params: [like],
+        };
+    }
+    return {
+        sql: `SELECT count(*) FROM ${table} WHERE (${params.columns
+            .map((c) => `${quoteIdent(c)} LIKE ? ESCAPE '\\'`)
+            .join(" OR ")})`,
+        params: params.columns.map(() => like),
+    };
+}

package/dist/analysis/data/sql-guard.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Lexical guard of `data_query` (spec §17.3). `node:sqlite` has no authorizer or progress
+ * handler and `DatabaseSync.prepare()` silently ignores text after the first statement, so the
+ * guard checks the SQL itself: exactly one statement, starting with SELECT or WITH, without
+ * write, schema, transaction or extension keywords outside literals and comments. The read-only
+ * connection (`readOnly`, `query_only`, extensions off) is the second line of defence.
+ */
+export type GuardResult = {
+    ok: true;
+    sql: string;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Validates a model-written query. Accepts one `SELECT`/`WITH` statement (a single trailing `;`
+ * is allowed and removed). Keywords inside literals, comments and quoted identifiers are fine;
+ * `replace(…)` as a function is fine (REPLACE INTO is not).
+ */
+export declare function guardSql(sql: string): GuardResult;

package/dist/analysis/data/sql-guard.js

@@ -0,0 +1,129 @@
+/**
+ * Lexical guard of `data_query` (spec §17.3). `node:sqlite` has no authorizer or progress
+ * handler and `DatabaseSync.prepare()` silently ignores text after the first statement, so the
+ * guard checks the SQL itself: exactly one statement, starting with SELECT or WITH, without
+ * write, schema, transaction or extension keywords outside literals and comments. The read-only
+ * connection (`readOnly`, `query_only`, extensions off) is the second line of defence.
+ */
+const FORBIDDEN = new Set([
+    "ATTACH",
+    "DETACH",
+    "PRAGMA",
+    "INSERT",
+    "UPDATE",
+    "DELETE",
+    "REPLACE",
+    "CREATE",
+    "DROP",
+    "ALTER",
+    "VACUUM",
+    "REINDEX",
+    "ANALYZE",
+    "BEGIN",
+    "COMMIT",
+    "ROLLBACK",
+    "SAVEPOINT",
+    "RELEASE",
+    "LOAD_EXTENSION",
+]);
+const isWordStart = (c) => /[A-Za-z_]/.test(c);
+const isWordChar = (c) => /[A-Za-z0-9_$]/.test(c);
+/**
+ * Splits SQL into significant tokens, skipping whitespace, comments and the contents of string
+ * literals and quoted identifiers. Returns an error text for an unterminated literal or comment.
+ */
+function tokenize(sql) {
+    const tokens = [];
+    const n = sql.length;
+    let i = 0;
+    while (i < n) {
+        const c = sql[i];
+        if (c === "'" || c === '"' || c === "`") {
+            let j = i + 1;
+            for (;;) {
+                if (j >= n)
+                    return { error: `Unterminated ${c === "'" ? "string" : "identifier"}` };
+                if (sql[j] === c) {
+                    if (sql[j + 1] === c) {
+                        j += 2;
+                        continue;
+                    }
+                    break;
+                }
+                j++;
+            }
+            // A quoted identifier or string is a value, not a keyword; it still counts as a token so
+            // that "SELECT" 1 is not mistaken for an empty statement.
+            tokens.push({ type: "punct", text: c });
+            i = j + 1;
+        }
+        else if (c === "[") {
+            const end = sql.indexOf("]", i + 1);
+            if (end < 0)
+                return { error: "Unterminated identifier" };
+            tokens.push({ type: "punct", text: "[" });
+            i = end + 1;
+        }
+        else if (c === "-" && sql[i + 1] === "-") {
+            const end = sql.indexOf("\n", i + 2);
+            i = end < 0 ? n : end + 1;
+        }
+        else if (c === "/" && sql[i + 1] === "*") {
+            const end = sql.indexOf("*/", i + 2);
+            if (end < 0)
+                return { error: "Unterminated comment" };
+            i = end + 2;
+        }
+        else if (/\s/.test(c)) {
+            i++;
+        }
+        else if (isWordStart(c)) {
+            let j = i + 1;
+            while (j < n && isWordChar(sql[j]))
+                j++;
+            tokens.push({ type: "word", text: sql.slice(i, j) });
+            i = j;
+        }
+        else {
+            tokens.push({ type: "punct", text: c });
+            i++;
+        }
+    }
+    return { tokens };
+}
+/**
+ * Validates a model-written query. Accepts one `SELECT`/`WITH` statement (a single trailing `;`
+ * is allowed and removed). Keywords inside literals, comments and quoted identifiers are fine;
+ * `replace(…)` as a function is fine (REPLACE INTO is not).
+ */
+export function guardSql(sql) {
+    const scanned = tokenize(sql);
+    if ("error" in scanned)
+        return { ok: false, reason: scanned.error };
+    const { tokens } = scanned;
+    // Drop one trailing semicolon; any other one separates statements.
+    if (tokens.at(-1)?.text === ";")
+        tokens.pop();
+    if (!tokens.length)
+        return { ok: false, reason: "The query is empty" };
+    if (tokens.some((t) => t.type === "punct" && t.text === ";"))
+        return { ok: false, reason: "Only one statement is allowed (no `;` between statements)" };
+    const first = tokens[0];
+    if (first.type !== "word" || !["SELECT", "WITH"].includes(first.text.toUpperCase()))
+        return { ok: false, reason: "Only SELECT and WITH queries are allowed" };
+    for (let i = 0; i < tokens.length; i++) {
+        const token = tokens[i];
+        if (token.type !== "word")
+            continue;
+        const word = token.text.toUpperCase();
+        if (!FORBIDDEN.has(word))
+            continue;
+        if (word === "REPLACE" && tokens[i + 1]?.text === "(")
+            continue;
+        return {
+            ok: false,
+            reason: `\`${token.text}\` is not allowed in a read-only query (quote column names that look like keywords, e.g. "${token.text}")`,
+        };
+    }
+    return { ok: true, sql };
+}

package/dist/analysis/data/stats.d.ts

@@ -0,0 +1,18 @@
+/** Minimal view of `node:sqlite`'s `DatabaseSync` (the engine runs outside the type roots). */
+export interface Db {
+    exec(sql: string): void;
+    prepare(sql: string): {
+        run(...params: unknown[]): unknown;
+        get(...params: unknown[]): unknown;
+        all(...params: unknown[]): unknown[];
+    };
+}
+export declare const INGEST_VERSION = 1;
+/** Distinct counts and top values are exact up to this many rows; above, a sample is used. */
+export declare const EXACT_DISTINCT_ROWS = 1000000;
+export declare const META_SCHEMA = "\nCREATE TABLE IF NOT EXISTS _alisio_meta(key TEXT PRIMARY KEY, value TEXT);\nCREATE TABLE IF NOT EXISTS _alisio_sheets(ordinal INTEGER PRIMARY KEY, name TEXT NOT NULL,\n  table_name TEXT NOT NULL, rows INTEGER NOT NULL, columns INTEGER NOT NULL);\nCREATE TABLE IF NOT EXISTS _alisio_columns(table_name TEXT NOT NULL, ordinal INTEGER NOT NULL,\n  name TEXT NOT NULL, label TEXT NOT NULL, inferred_type TEXT NOT NULL,\n  nulls INTEGER, distinct_count INTEGER, distinct_exact INTEGER,\n  min TEXT, max TEXT, mean REAL, text_fallbacks INTEGER, top_values TEXT,\n  PRIMARY KEY(table_name, ordinal));\n";
+/**
+ * Computes `_alisio_columns` statistics for every registered column and refreshes the row and
+ * column counts of `_alisio_sheets`. Column rows (table, ordinal, name, label) must exist.
+ */
+export declare function finalizeDatabase(db: Db): void;

package/dist/analysis/data/stats.js

@@ -0,0 +1,77 @@
+/**
+ * Metadata tables of a dataset file and the per-column statistics (spec §17.2). The same
+ * `finalizeDatabase` runs after Node parses a CSV/TSV/JSON/JSONL file and after the Python helper
+ * converts an XLSX workbook, so both routes produce identical types and statistics.
+ */
+import { inferType, quoteIdent } from "./infer.js";
+export const INGEST_VERSION = 1;
+/** Distinct counts and top values are exact up to this many rows; above, a sample is used. */
+export const EXACT_DISTINCT_ROWS = 1_000_000;
+const SAMPLE_ROWS = 200_000;
+const TYPE_SAMPLE = 1000;
+export const META_SCHEMA = `
+CREATE TABLE IF NOT EXISTS _alisio_meta(key TEXT PRIMARY KEY, value TEXT);
+CREATE TABLE IF NOT EXISTS _alisio_sheets(ordinal INTEGER PRIMARY KEY, name TEXT NOT NULL,
+  table_name TEXT NOT NULL, rows INTEGER NOT NULL, columns INTEGER NOT NULL);
+CREATE TABLE IF NOT EXISTS _alisio_columns(table_name TEXT NOT NULL, ordinal INTEGER NOT NULL,
+  name TEXT NOT NULL, label TEXT NOT NULL, inferred_type TEXT NOT NULL,
+  nulls INTEGER, distinct_count INTEGER, distinct_exact INTEGER,
+  min TEXT, max TEXT, mean REAL, text_fallbacks INTEGER, top_values TEXT,
+  PRIMARY KEY(table_name, ordinal));
+`;
+/**
+ * Computes `_alisio_columns` statistics for every registered column and refreshes the row and
+ * column counts of `_alisio_sheets`. Column rows (table, ordinal, name, label) must exist.
+ */
+export function finalizeDatabase(db) {
+    const sheets = db
+        .prepare("SELECT ordinal, table_name FROM _alisio_sheets ORDER BY ordinal")
+        .all();
+    db.exec("BEGIN");
+    try {
+        for (const sheet of sheets) {
+            const table = quoteIdent(sheet.table_name);
+            const rows = db.prepare(`SELECT count(*) AS n FROM ${table}`).get().n;
+            const columns = db
+                .prepare("SELECT table_name, ordinal, name FROM _alisio_columns WHERE table_name=? ORDER BY ordinal")
+                .all(sheet.table_name);
+            db.prepare("UPDATE _alisio_sheets SET rows=?, columns=? WHERE ordinal=?").run(rows, columns.length, sheet.ordinal);
+            const exact = rows <= EXACT_DISTINCT_ROWS;
+            const stride = exact ? 1 : Math.ceil(rows / SAMPLE_ROWS);
+            const andWhere = exact ? "" : `AND rowid % ${stride} = 0`;
+            for (const column of columns) {
+                const col = quoteIdent(column.name);
+                const sample = db
+                    .prepare(`SELECT typeof(${col}) AS kind, ${col} AS value FROM ${table} LIMIT ${TYPE_SAMPLE}`)
+                    .all();
+                const type = inferType(sample);
+                const agg = db
+                    .prepare(`SELECT sum(${col} IS NULL) AS nulls, min(${col}) AS mn, max(${col}) AS mx,
+               sum(typeof(${col}) IN ('integer','real')) AS nums,
+               sum(typeof(${col})='text') AS texts,
+               sum(typeof(${col})='text' AND ${col} GLOB '*[0-9]*' AND NOT ${col} GLOB '*[A-Za-z]*') AS numlike,
+               avg(CASE WHEN typeof(${col}) IN ('integer','real') THEN ${col} END) AS mean
+             FROM ${table}`)
+                    .get();
+                const groups = db
+                    .prepare(`WITH g AS MATERIALIZED (
+               SELECT ${col} AS v, count(*) AS n FROM ${table}
+               WHERE ${col} IS NOT NULL ${andWhere} GROUP BY ${col})
+             SELECT (SELECT count(*) FROM g) AS d, CAST(v AS TEXT) AS v, n FROM g
+             ORDER BY n DESC, v LIMIT 5`)
+                    .all();
+                const nums = Number(agg.nums ?? 0);
+                const texts = Number(agg.texts ?? 0);
+                const fallbacks = nums > 0 ? texts : type === "text" ? Number(agg.numlike ?? 0) : 0;
+                const numeric = type === "integer" || type === "real";
+                db.prepare(`UPDATE _alisio_columns SET inferred_type=?, nulls=?, distinct_count=?, distinct_exact=?,
+             min=?, max=?, mean=?, text_fallbacks=?, top_values=? WHERE table_name=? AND ordinal=?`).run(type, Number(agg.nulls ?? 0), Number(groups[0]?.d ?? 0), exact ? 1 : 0, agg.mn === null || agg.mn === undefined ? null : String(agg.mn), agg.mx === null || agg.mx === undefined ? null : String(agg.mx), numeric && agg.mean !== null ? Number(agg.mean) : null, fallbacks, JSON.stringify(groups.map((g) => ({ value: g.v, count: Number(g.n) }))), sheet.table_name, column.ordinal);
+            }
+        }
+        db.exec("COMMIT");
+    }
+    catch (error) {
+        db.exec("ROLLBACK");
+        throw error;
+    }
+}

package/dist/analysis/install-hints.d.ts

@@ -0,0 +1,33 @@
+export interface HintHost {
+    platform: NodeJS.Platform;
+    arch: string;
+    /** Linux `/etc/os-release` fields (`ID`, `ID_LIKE`, `PRETTY_NAME`, `VERSION_ID`). */
+    osRelease?: Record<string, string>;
+    hasUv?: boolean;
+    hasWinget?: boolean;
+    hasBrew?: boolean;
+    /** A Python that was found but is too old (or a `--python` that failed). */
+    found?: {
+        version?: string;
+        path: string;
+        reason?: string;
+    };
+}
+export interface InstallHints {
+    /** `Linux · Ubuntu 22.04 · x86_64` */
+    system: string;
+    /** Optional heading line (found Python too old, `--python` not usable). */
+    heading?: string;
+    primary: string;
+    alternatives: string[];
+    notes: string[];
+}
+/** Parses `KEY=value` / `KEY="value"` lines of an os-release file. */
+export declare function parseOsRelease(text: string): Record<string, string>;
+export declare function pythonInstallHints(host: HintHost): InstallHints;
+/** One paragraph for the model and terminals (English, like every tool message). */
+export declare function installHintsText(hints: InstallHints): string;
+/** The same guidance as Markdown (web and TUI render it as a `markdown` block). */
+export declare function installHintsMarkdown(hints: InstallHints): string;
+/** Detects the host for `pythonInstallHints` (reads files and PATH only; launches nothing). */
+export declare function detectHintHost(found?: HintHost["found"]): Promise<HintHost>;