@alisio/core 0.1.0-alpha.9 → 0.1.0

package/dist/analysis/rerun.d.ts

@@ -0,0 +1,40 @@
+import type { ArtifactStore } from "../artifacts/store.ts";
+import type { DatasetService } from "./data/datasets.ts";
+import type { AnalysisJobs, JobInput } from "./jobs.ts";
+export interface RerunInput extends JobInput {
+    /** Absolute file to copy into the new job's `input/` (verified before). */
+    source: string;
+}
+export interface RerunPlan {
+    /** The execution being repeated. */
+    executionId: string;
+    /** The artifact the user pointed at, when the reference was an artifact. */
+    artifactId?: string;
+    code: string;
+    scriptSha256: string;
+    inputs: RerunInput[];
+    manifest: unknown[];
+    extras: Array<"analysis" | "science">;
+    /** The runtime of the original execution (a rerun uses the configured runtime now). */
+    runtime: "managed" | "oci";
+}
+export type RerunPreparation = {
+    ok: true;
+    plan: RerunPlan;
+} | {
+    ok: false;
+    problems: string[];
+};
+export declare function sha256OfFile(path: string): Promise<string>;
+export declare class AnalysisRerun {
+    private options;
+    constructor(options: {
+        jobs: AnalysisJobs;
+        store: ArtifactStore;
+        datasets?: DatasetService;
+    });
+    /** The script of a saved execution as a preview (approvals show it), or undefined. */
+    script(ref: string, rootSessionId: string): Promise<string | undefined>;
+    private resolve;
+    prepare(ref: string, rootSessionId: string): Promise<RerunPreparation>;
+}

package/dist/analysis/rerun.js

@@ -0,0 +1,136 @@
+/**
+ * Rerun of a `python_run` execution (spec §19): the same `script/main.py` and the same inputs,
+ * verified by sha256, as a NEW execution with new artifacts. Nothing of the original is touched.
+ * When the saved script, an input copy or a dataset is missing or no longer matches its recorded
+ * hash, nothing runs and every problem is reported.
+ */
+import { createHash } from "node:crypto";
+import { createReadStream } from "node:fs";
+import { readdir, readFile } from "node:fs/promises";
+import { basename, join } from "node:path";
+export async function sha256OfFile(path) {
+    const hash = createHash("sha256");
+    for await (const chunk of createReadStream(path))
+        hash.update(chunk);
+    return hash.digest("hex");
+}
+const fail = (...problems) => ({ ok: false, problems });
+export class AnalysisRerun {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    /** The script of a saved execution as a preview (approvals show it), or undefined. */
+    async script(ref, rootSessionId) {
+        const resolved = this.resolve(ref, rootSessionId);
+        if (!("executionId" in resolved))
+            return undefined;
+        const details = this.options.jobs.details(resolved.executionId);
+        if (!details)
+            return undefined;
+        try {
+            return await readFile(join(this.options.jobs.folder(details.relDir), "script", "main.py"), "utf8");
+        }
+        catch {
+            return undefined;
+        }
+    }
+    resolve(ref, rootSessionId) {
+        if (ref.startsWith("art_")) {
+            const record = this.options.store.get(ref);
+            if (!record || record.sessionId !== rootSessionId)
+                return { problem: `Artifact ${ref} was not found in this session` };
+            if (!record.executionId)
+                return {
+                    problem: `${record.fileName} was not produced by python_run, so it has no script to run again`,
+                };
+            if (record.status === "deleted")
+                return {
+                    problem: `${record.fileName} was deleted; run the analysis again from its script instead`,
+                };
+            return { executionId: record.executionId, artifactId: record.id };
+        }
+        if (ref.startsWith("exec_"))
+            return { executionId: ref };
+        return { problem: `${ref} is neither an artifact (art_…) nor an execution (exec_…) id` };
+    }
+    async prepare(ref, rootSessionId) {
+        const resolved = this.resolve(ref, rootSessionId);
+        if ("problem" in resolved)
+            return fail(resolved.problem);
+        const { jobs, datasets } = this.options;
+        const details = jobs.details(resolved.executionId);
+        if (!details || details.rootSessionId !== rootSessionId)
+            return fail(`Execution ${resolved.executionId} was not found in this session`);
+        let folder;
+        try {
+            folder = jobs.folder(details.relDir);
+        }
+        catch (error) {
+            return fail(error instanceof Error ? error.message : String(error));
+        }
+        let code;
+        try {
+            code = await readFile(join(folder, "script", "main.py"), "utf8");
+        }
+        catch {
+            return fail(`The script of ${details.id} is no longer available (the retention sweep removes the scripts of executions without ready artifacts)`);
+        }
+        if (createHash("sha256").update(code).digest("hex") !== details.scriptSha256)
+            return fail(`The saved script of ${details.id} does not match its recorded hash`);
+        const recorded = await jobs.recordedInputs(details.relDir);
+        const problems = [];
+        const inputs = [];
+        if (!recorded) {
+            const present = await readdir(join(folder, "input")).catch(() => []);
+            if (present.some((name) => name !== "inputs.json"))
+                problems.push(`The inputs of ${details.id} were not recorded, so they cannot be verified`);
+        }
+        else
+            for (const input of recorded.inputs) {
+                // `job.json` is internal, but a name is never trusted to leave `input/`.
+                if (typeof input.name !== "string" || basename(input.name) !== input.name) {
+                    problems.push("The recorded inputs of this execution are not valid");
+                    continue;
+                }
+                if (input.datasetId) {
+                    const record = datasets?.get(input.datasetId);
+                    if (!record || record.rootSessionId !== rootSessionId)
+                        problems.push(`Input ${input.name}: the dataset ${input.datasetId} no longer exists`);
+                    else if (record.sha256 !== input.sha256)
+                        problems.push(`Input ${input.name}: the dataset ${input.datasetId} changed`);
+                    else
+                        inputs.push({ ...input, source: datasets?.file(record) });
+                    continue;
+                }
+                const source = join(folder, "input", input.name);
+                let actual;
+                try {
+                    actual = await sha256OfFile(source);
+                }
+                catch {
+                    problems.push(`Input ${input.name} is missing`);
+                    continue;
+                }
+                if (actual !== (input.copySha256 ?? input.sha256))
+                    problems.push(`Input ${input.name} changed (its sha256 no longer matches the original)`);
+                else
+                    inputs.push({ ...input, source });
+            }
+        if (problems.length)
+            return { ok: false, problems };
+        return {
+            ok: true,
+            plan: {
+                executionId: details.id,
+                ...(resolved.artifactId ? { artifactId: resolved.artifactId } : {}),
+                code,
+                scriptSha256: details.scriptSha256,
+                inputs,
+                manifest: recorded?.manifest ?? [],
+                extras: (recorded?.extras ?? []).filter((e) => e === "analysis" || e === "science"),
+                runtime: details.runtime,
+            },
+        };
+    }
+}

package/dist/analysis/runtime-manager.d.ts

@@ -0,0 +1,146 @@
+import type { InstallPreview } from "@alisio/sdk";
+export declare const MIN_PYTHON: readonly [number, number];
+/** Prints `[[major, minor, micro], executable]` as JSON. */
+export declare const PROBE_CODE = "import sys, json; print(json.dumps([list(sys.version_info[:3]), sys.executable]))";
+export type CandidateSource = "flag" | "uv" | "py" | "python3" | "python";
+export interface PythonCandidate {
+    source: CandidateSource;
+    /** Absolute path of the launcher or interpreter found on PATH (or the `--python` path). */
+    command: string;
+}
+export interface FileInfo {
+    mtimeMs: number;
+    isFile: boolean;
+}
+export interface DiscoveryDeps {
+    platform: NodeJS.Platform;
+    /** `PATH` of the process. */
+    path: string;
+    /** Windows `PATHEXT`. */
+    pathext?: string;
+    /** Windows `%LOCALAPPDATA%` (to skip the Microsoft Store alias). */
+    localAppData?: string;
+    stat(path: string): Promise<FileInfo | undefined>;
+    /** Runs a probe; never a shell. */
+    exec(command: string, args: string[], signal: AbortSignal): Promise<{
+        stdout: string;
+        exitCode: number;
+    }>;
+}
+export type PythonResolution = {
+    ok: true;
+    executable: string;
+    version: string;
+    source: CandidateSource;
+    venv?: boolean;
+    /** Arguments placed before the interpreter flags (embedders and test launchers only). */
+    prefixArgs?: string[];
+} | {
+    ok: false;
+    /** Human-readable cause. */
+    reason: string;
+    /** A Python that was found but is too old, or the unusable `--python`. */
+    found?: {
+        version?: string;
+        path: string;
+        reason?: string;
+    };
+    /** `--python` was given (no other candidate was tried). */
+    flag?: boolean;
+};
+/** The interpreter of a virtual environment, built with the target platform's path rules. */
+export declare function venvInterpreter(venv: string, platform?: NodeJS.Platform): string;
+/** `3.10.12` → true when at least `MIN_PYTHON`. */
+export declare function supportedVersion(version: string): boolean;
+/** Parses the probe output; undefined when it is not ours. */
+export declare function parseProbe(stdout: string): {
+    version: string;
+    executable: string;
+} | undefined;
+export declare function defaultDiscoveryDeps(): DiscoveryDeps;
+export type Extras = "analysis" | "science";
+/**
+ * The installation failed. `offline` means the download could not start or finish because there
+ * is no network (or the package index is unreachable): nothing was installed and the base runtime
+ * is untouched, so the message says so and how to retry.
+ */
+export declare class ExtrasInstallError extends Error {
+    readonly kind: "offline" | "failed";
+    constructor(message: string, kind: "offline" | "failed");
+}
+/** The command that installs the extras by hand (the optional, explicit route). */
+export declare const setupCommand: (extras: Extras) => string;
+/** What an `analysis.install` approval shows for a set of extras. */
+export declare function installPreview(extras: Extras): InstallPreview;
+/** Runs one installation step (replaceable in tests so no network or pip is needed). */
+export type InstallStep = (command: string, args: string[], options: {
+    cwd: string;
+    signal: AbortSignal;
+    onOutput?: (text: string) => void;
+}) => Promise<{
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+}>;
+/** Persisted state of an extras environment (`runtime.json`). */
+export interface RuntimeState {
+    runtimeVersion: string;
+    python: string;
+    pythonVersion: string;
+    extras: Extras[];
+    createdAt: number;
+    ok: boolean;
+}
+export declare class AnalysisRuntimeManager {
+    private options;
+    readonly deps: DiscoveryDeps;
+    private memory?;
+    constructor(options: {
+        /** State root (`stateHome()` or the folder of `--db`). */
+        stateDir: string;
+        /** `--python <path>`: pins the interpreter; nothing else is tried. */
+        python?: string;
+        deps?: Partial<DiscoveryDeps>;
+        /** Replaces the installation steps (tests: a fake pip, no network). */
+        install?: InstallStep;
+    });
+    get pythonFlag(): string | undefined;
+    private get dir();
+    private sep;
+    /** First PATH match of `name` (with `PATHEXT` on Windows), by `stat` only. */
+    private onPath;
+    /** The Microsoft Store alias opens the Store instead of running Python. */
+    private storeAlias;
+    /** Candidate executables, in discovery order (stat only; launches nothing). */
+    candidates(): Promise<PythonCandidate[]>;
+    private readCache;
+    private writeCache;
+    /** Probes one interpreter path: its version and real executable, or undefined. */
+    private probe;
+    /**
+     * The interpreter to run: the cached one while its file is unchanged, else a fresh discovery.
+     * With `--python`, only that path is considered.
+     */
+    resolve(signal?: AbortSignal): Promise<PythonResolution>;
+    /** The interpreter `python_run` uses: an installed extras environment, else the base one. */
+    interpreter(signal?: AbortSignal): Promise<PythonResolution & {
+        extras?: Extras[];
+        runtimeVersion?: string;
+    }>;
+    /** The extras environment recorded by `alisio analysis setup --extras`, when healthy. */
+    activeRuntime(): Promise<RuntimeState | undefined>;
+    private installing;
+    /** Whether the healthy extras environment already provides `extras` (`science` includes `analysis`). */
+    hasExtras(extras: Extras): Promise<boolean>;
+    /**
+     * Creates the extras environment and installs the hash-locked wheels (`--require-hashes`,
+     * `--only-binary=:all:`; nothing is compiled). Needs network. Never called by `python_run`
+     * without an `analysis.install` approval. Failing (offline, no wheel for this platform) leaves
+     * no half-built environment and does not touch the active one. Concurrent calls share one run.
+     */
+    installExtras(extras: Extras, options: {
+        signal: AbortSignal;
+        onOutput?: (text: string) => void;
+    }): Promise<RuntimeState>;
+    private doInstall;
+}