@alisio/core 0.1.0-alpha.9 → 0.1.1

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>;

package/dist/analysis/install-hints.js

@@ -0,0 +1,144 @@
+/**
+ * Install instructions for Python ≥ 3.10 on the machine Alisio runs on. A pure function of the
+ * detected host (injected in tests); the host detection reads `/etc/os-release` and looks for
+ * `uv`, `winget` and `brew` on PATH without launching any process. Commands are shown, never run.
+ */
+import { readFile } from "node:fs/promises";
+import { which } from "../runtime/fs.js";
+const UV = "uv python install 3.12";
+const PYTHON_ORG = "Download the installer from https://www.python.org/downloads/";
+/** Parses `KEY=value` / `KEY="value"` lines of an os-release file. */
+export function parseOsRelease(text) {
+    const out = {};
+    for (const line of text.split(/\r?\n/)) {
+        const match = /^([A-Z_]+)=(.*)$/.exec(line.trim());
+        if (match?.[1])
+            out[match[1]] = (match[2] ?? "").replace(/^["']|["']$/g, "");
+    }
+    return out;
+}
+function systemLabel(host) {
+    const os = host.platform === "win32"
+        ? "Windows"
+        : host.platform === "darwin"
+            ? "macOS"
+            : host.platform === "linux"
+                ? "Linux"
+                : host.platform;
+    const distro = host.osRelease?.PRETTY_NAME;
+    return [os, distro, host.arch].filter(Boolean).join(" · ");
+}
+export function pythonInstallHints(host) {
+    const system = systemLabel(host);
+    const heading = host.found
+        ? host.found.version
+            ? `Found Python ${host.found.version} at ${host.found.path}; Alisio needs 3.10 or newer.`
+            : `The Python at ${host.found.path} is not usable${host.found.reason ? ` (${host.found.reason})` : ""}.`
+        : undefined;
+    const notes = [];
+    if (host.found)
+        notes.push("If another Python 3.10+ is installed, start Alisio with --python <path>.");
+    let primary;
+    let alternatives = [];
+    if (host.platform === "win32") {
+        primary = "winget install Python.Python.3.12";
+        alternatives = [`${PYTHON_ORG} (check "Add python.exe to PATH")`];
+        if (host.hasUv)
+            alternatives.push(UV);
+        notes.push("The Microsoft Store alias (WindowsApps\\python.exe) does not count as an installed Python.", "Open a new terminal after installing so the updated PATH is visible.");
+    }
+    else if (host.platform === "darwin") {
+        if (host.hasBrew) {
+            primary = "brew install python@3.12";
+            alternatives = [
+                "Download the macOS installer from https://www.python.org/downloads/macos/",
+                UV,
+            ];
+        }
+        else {
+            primary = "Download the macOS installer from https://www.python.org/downloads/macos/";
+            alternatives = [
+                UV,
+                "xcode-select --install (Command Line Tools Python; it may be older than 3.10)",
+            ];
+        }
+    }
+    else if (host.platform === "linux") {
+        const ids = `${host.osRelease?.ID ?? ""} ${host.osRelease?.ID_LIKE ?? ""}`.toLowerCase();
+        const has = (id) => ids.split(/\s+/).includes(id);
+        if (has("debian") || has("ubuntu")) {
+            primary = "sudo apt install python3";
+            alternatives = [`If your distribution ships a version older than 3.10: ${UV}`];
+        }
+        else if (has("fedora") || has("rhel") || has("centos")) {
+            primary = "sudo dnf install python3";
+            alternatives = [UV];
+        }
+        else if (has("arch")) {
+            primary = "sudo pacman -S python";
+        }
+        else if (ids.includes("suse")) {
+            primary = "sudo zypper install python3";
+        }
+        else if (has("alpine")) {
+            primary = "sudo apk add python3";
+        }
+        else {
+            primary = "Install python3 with your system package manager";
+            alternatives = [UV];
+        }
+    }
+    else {
+        primary = "Install python3 with your system package manager";
+        alternatives = [UV];
+    }
+    return { system, ...(heading ? { heading } : {}), primary, alternatives, notes };
+}
+/** One paragraph for the model and terminals (English, like every tool message). */
+export function installHintsText(hints) {
+    const lines = [
+        ...(hints.heading ? [hints.heading] : []),
+        `Python 3.10+ was not found on this machine (${hints.system}). To install it: ${hints.primary}`,
+        ...hints.alternatives.map((alternative) => `Alternatively: ${alternative}`),
+        ...hints.notes,
+        "After installing, ask again; no Alisio restart is needed. To use a specific interpreter, start Alisio with --python <path>.",
+    ];
+    return lines.join("\n");
+}
+/** The same guidance as Markdown (web and TUI render it as a `markdown` block). */
+export function installHintsMarkdown(hints) {
+    return [
+        "**Python 3.10+ is not available**",
+        "",
+        ...(hints.heading ? [hints.heading, ""] : []),
+        `Detected system: ${hints.system}`,
+        "",
+        "```sh",
+        hints.primary,
+        "```",
+        ...(hints.alternatives.length
+            ? ["", "Alternatives:", ...hints.alternatives.map((a) => `- ${a}`)]
+            : []),
+        ...(hints.notes.length ? ["", ...hints.notes.map((n) => `- ${n}`)] : []),
+        "",
+        "After installing, ask again; no restart is needed. Start Alisio with `--python <path>` to pin an interpreter.",
+    ].join("\n");
+}
+/** Detects the host for `pythonInstallHints` (reads files and PATH only; launches nothing). */
+export async function detectHintHost(found) {
+    let osRelease;
+    if (process.platform === "linux")
+        osRelease = await readFile("/etc/os-release", "utf8")
+            .then(parseOsRelease)
+            .catch(() => undefined);
+    const [uv, winget, brew] = await Promise.all([which("uv"), which("winget"), which("brew")]);
+    return {
+        platform: process.platform,
+        arch: process.arch,
+        ...(osRelease ? { osRelease } : {}),
+        hasUv: !!uv,
+        hasWinget: !!winget,
+        hasBrew: !!brew,
+        ...(found ? { found } : {}),
+    };
+}

package/dist/analysis/janitor.d.ts

@@ -0,0 +1,60 @@
+import type { SqlDatabase } from "@alisio/sdk";
+import type { ArtifactStore } from "../artifacts/store.ts";
+import type { BlobStore } from "../runtime/blobs.ts";
+import type { DatasetService } from "./data/datasets.ts";
+export declare const SWEEP_INTERVAL_MS = 86400000;
+export interface RetentionPolicy {
+    jobsDays: number;
+    intermediateDays: number;
+    artifactsDays: number;
+}
+export interface SweepReport {
+    /** Why nothing ran: swept less than 24 h ago, or another process is sweeping. */
+    skipped?: "recent" | "locked";
+    workDeleted: number;
+    jobsTrimmed: number;
+    jobsDeleted: number;
+    artifactsExpired: number;
+    datasetsDeleted: number;
+    uploadsDeleted: number;
+    bytesFreed: number;
+    errors: number;
+}
+export declare class AnalysisJanitor {
+    private options;
+    private timer?;
+    private stopped;
+    constructor(options: {
+        /** State root (`stateHome()` or the folder of `--db`). */
+        root: string;
+        db: SqlDatabase;
+        artifacts: ArtifactStore;
+        datasets?: DatasetService;
+        blobs?: BlobStore;
+        /** Read at every sweep, so a changed setting applies without a restart. */
+        retention: () => RetentionPolicy;
+        /** The clock (injected in tests). */
+        now?: () => number;
+        /** Delay before the first background sweep after `start()` (default 30 s). */
+        initialDelayMs?: number;
+    });
+    private now;
+    private get dir();
+    /** When the last sweep started (epoch ms), if there was one. */
+    lastSweep(): Promise<number | undefined>;
+    /** Launches the sweep in the background; never delays the caller and never keeps Node alive. */
+    start(): void;
+    stop(): void;
+    private arm;
+    /** One sweep (see the module comment). `force` ignores the 24 h mark. */
+    sweep(options?: {
+        force?: boolean;
+    }): Promise<SweepReport>;
+    /** Exclusive lock between processes sharing the state folder; undefined when someone holds it. */
+    private lock;
+    private expireArtifacts;
+    private trimJobs;
+    /** Removes the empty session and workspace folders a deleted job leaves behind. */
+    private pruneEmptyParents;
+    private dropDatasets;
+}