@rho-workspace/rho 0.5.3 → 0.5.4

package/node_modules/@rho-workspace/plugin-kernel/dist/index.d.ts

@@ -27,6 +27,7 @@ export interface SessionRecord {
     cells: number;
     place?: SessionPlace | null;
     host?: string | null;
+    program?: string | null;
 }
 export interface SessionPlace {
     placeId: string;
@@ -80,6 +81,8 @@ export interface CellRecord {
         path: string;
         how: 'read' | 'wrote';
     }>;
+    program?: string | null;
+    version?: string | null;
 }
 export type InspectInput = {
     language: Language;
@@ -142,6 +145,7 @@ export declare class KernelHost {
     private loading?;
     private turn;
     private exclusive;
+    private programs;
     private placesRead?;
     private placesWriting;
     private ssh;
@@ -154,6 +158,8 @@ export declare class KernelHost {
         serverctl?: string;
         onChange?: () => void;
     });
+    private program;
+    private named;
     private transport;
     private get limits();
     private folder;
@@ -180,6 +186,7 @@ export declare class KernelHost {
         by: string;
         waitMs?: number;
         place?: string;
+        interpreter?: string;
     }): Promise<{
         cell: CellRecord;
         session: SessionRecord;

package/node_modules/@rho-workspace/plugin-kernel/dist/index.js

@@ -1,5 +1,6 @@
 import { spawn } from 'node:child_process';
 import * as fs from 'node:fs/promises';
+import { constants as fsConstants } from 'node:fs';
 import net from 'node:net';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -96,6 +97,9 @@ export class KernelHost {
         this.turn = next.catch(() => { });
         return next;
     }
+    // The program each language's sessions start with when the project has named one (a path in
+    // the project, as named): the last one a cell named, until another is named.
+    programs = {};
     placesRead;
     placesWriting = Promise.resolve();
     ssh;
@@ -107,6 +111,24 @@ export class KernelHost {
         const limits = this.limits;
         this.serverctl = new Serverctl(options.serverctl ?? 'serverctl', { reuseS: 60, sessionS: limits.serverctlSessionS, readMs: limits.serverctlReadMs, skillBytes: limits.serverSkillBytes });
     }
+    // A program named for a session: one in a folder of the project, such as the python of a
+    // virtual environment made there (.venv/bin/python). Its folder must be the project's own; the
+    // file itself may be the link a virtual environment makes to the Python it was made from, and
+    // it is started by that name so the environment is the one that runs.
+    async program(named) {
+        const root = await fs.realpath(this.root), file = path.resolve(root, named);
+        const folder = await fs.realpath(path.dirname(file)).catch(() => null);
+        requireThat(folder && (folder === root || folder.startsWith(root + path.sep)), 'scope', `Name a program in a folder of this project, such as .venv/bin/python; ${named} is not.`, { interpreter: named });
+        const program = path.join(folder, path.basename(file));
+        const runs = await fs.stat(program).then(s => s.isFile(), () => false) && await fs.access(program, fsConstants.X_OK).then(() => true, () => false);
+        requireThat(runs, 'not_found', `${named} is not a program that can run here.`, { interpreter: named });
+        return program;
+    }
+    // A program in the project is named relative to it (.venv/bin/python), so the record stays true
+    // when the project moves; any other keeps the path the session reported.
+    named(live, program) {
+        return !live.place && program.startsWith(live.root + path.sep) ? path.relative(live.root, program) : program;
+    }
     transport(place) { return place.via === 'serverctl' ? this.serverctl : this.ssh; }
     get limits() { return { ...kernelLimits, ...this.options.limits }; }
     async folder() { return stateDirectory(this.root, '.rho/plugins/kernel'); }
@@ -114,6 +136,7 @@ export class KernelHost {
     load() { return this.loading ??= this.readRecord(); }
     async readRecord() {
         const state = await readJson(path.join(await this.folder(), 'state.json'), { sessions: [], cells: [] });
+        this.programs = state.programs ?? {};
         let changed = false;
         for (const s of state.sessions)
             if (s.state !== 'ended') {
@@ -134,7 +157,7 @@ export class KernelHost {
     save() {
         clearTimeout(this.saveTimer);
         this.saveTimer = undefined;
-        this.writing = this.writing.then(async () => atomicJson(path.join(await this.folder(), 'state.json'), { sessions: this.sessions ?? [], cells: this.cells }));
+        this.writing = this.writing.then(async () => atomicJson(path.join(await this.folder(), 'state.json'), { sessions: this.sessions ?? [], cells: this.cells, programs: this.programs }));
         return this.writing;
     }
     // Output arrives in many small pieces; it is written at most twice a second.
@@ -178,7 +201,7 @@ export class KernelHost {
         }
         else {
             requireThat(input.code.trim().length > 0 && Buffer.byteLength(input.code) <= this.limits.maxCodeBytes, 'invalid', `Write code of at most ${this.limits.maxCodeBytes} bytes.`, { limit: 'maxCodeBytes' });
-            const live = await this.ensure(input.language, input.by, input.place);
+            const live = await this.ensure(input.language, input.by, input.place, input.interpreter);
             requireThat(live.queue.length < this.limits.maxQueued, 'limit', `At most ${this.limits.maxQueued} cells wait in a session. Wait for some to run or interrupt the one running.`, { limit: 'maxQueued', maximum: this.limits.maxQueued });
             // The oldest finished cells make room, with their plots.
             while (this.cells.length >= this.limits.maxCells) {
@@ -202,14 +225,24 @@ export class KernelHost {
     // The language's live session, started for this caller when there is none: where the cell
     // names, else where the project runs that language (this machine unless chosen). A cell that
     // names another place than where the live session runs is refused; its values stay there.
-    async ensure(language, by, placeId) {
+    async ensure(language, by, placeId, interpreter) {
         const running = this.live.get(language), name = language === 'r' ? 'R' : 'Python';
         const where = (live) => live.place ? `on ${live.place.label}` : 'on this machine';
+        requireThat(!interpreter || !placeId || placeId === 'local', 'invalid', 'An interpreter names a program in the project on this machine; a session on a server runs that server\'s.');
+        const named = interpreter ? await this.program(interpreter) : null;
         if (running && !running.stopping) {
             requireThat(!placeId || placeId === (running.place?.placeId ?? 'local'), 'conflict', `The ${name} session runs ${where(running)}. Run the cell there, or stop that session first; its values stay until then.`, { place: running.place?.placeId ?? 'local' });
-            return running;
+            if (!named || !running.place && running.started === named)
+                return running;
+            // A session in which only this caller ran cells, none of them now, is its own to start
+            // again with the program it names. Once anyone else ran a cell there, the values are shared
+            // and only the person stops it.
+            const own = !running.place && !running.current && !running.queue.length && this.cells.filter(c => c.sessionId === running.record.sessionId).every(c => c.by === by);
+            requireThat(own, 'conflict', `The ${name} session runs ${running.record.program ?? 'another program'}${running.current || running.queue.length ? ' and has a cell running' : ', and others ran cells in it'}. Ask the person to stop it in the Notebook, then run this cell again to start one with ${interpreter}; its values stay until then.`, { program: running.started ?? running.record.program ?? null });
+            this.stopping(this.sessions, running.record.sessionId, by);
+            await running.ended;
         }
-        requireThat(!running, 'conflict', 'The session is stopping. Run the cell again when it has ended.');
+        requireThat(!this.live.get(language), 'conflict', 'The session is stopping. Run the cell again when it has ended.');
         const chosen = placeId ?? (await this.placeState()).use[language] ?? 'local';
         const place = chosen === 'local' ? null : (await this.placeState()).places.find(p => p.placeId === chosen) ?? null;
         requireThat(chosen === 'local' || place, 'not_found', `No place is named ${chosen}. Read kernel.places for the places there are.`);
@@ -220,7 +253,15 @@ export class KernelHost {
         if (old.length > this.limits.maxEndedSessions)
             this.sessions.splice(this.sessions.indexOf(old[0]), 1);
         const windows = !place && process.platform === 'win32';
-        const program = place ? 'ssh' : language === 'r' ? this.options.rscript ?? 'Rscript' : this.options.python ?? (windows ? 'python' : 'python3');
+        // A program the cell named, else the one the project named last while it is still there.
+        requireThat(!named || !place, 'invalid', `${name} runs on ${place?.label} in this project; an interpreter names a program in the project on this machine.`);
+        const kept = !named && !place && this.programs[language] ? await this.program(this.programs[language]).catch(() => null) : null;
+        if (named)
+            this.programs[language] = path.relative(await fs.realpath(this.root), named);
+        else if (!kept && this.programs[language])
+            delete this.programs[language];
+        const selected = named ?? kept;
+        const program = place ? 'ssh' : selected ?? (language === 'r' ? this.options.rscript ?? 'Rscript' : this.options.python ?? (windows ? 'python' : 'python3'));
         const root = await fs.realpath(this.root);
         // On a server the runner is sent first on the session's own input, named by its digest, so
         // the session needs nothing installed there but R or Python.
@@ -229,7 +270,9 @@ export class KernelHost {
         const pipe = windows && language === 'r' ? await answerPipe() : null;
         const child = place ? await this.transport(place).spawn(place, sessionCommand(place, language === 'r' ? 'Rscript' : 'python3', runner, source.length), root)
             : spawn(program, [runners[language], root], { cwd: root, ...ownGroup, stdio: ['pipe', 'pipe', 'pipe', 'pipe'], env: { ...process.env, MPLBACKEND: 'Agg', PYTHONUNBUFFERED: '1', ...(pipe ? { RHO_KERNEL_ANSWERS: pipe.name } : {}) } });
-        const live = { record, child, place, remotePid: null, answers: '', early: '', order: Promise.resolve(), queue: [], current: null, stopping: false, printed: '', mark: 0, held: [], answered: 0, looking: null, lookups: Promise.resolve(), pipe: pipe?.server };
+        let settle = () => { };
+        const ended = new Promise(resolve => { settle = resolve; });
+        const live = { started: selected, root, ended, settle, record, child, place, remotePid: null, answers: '', early: '', order: Promise.resolve(), queue: [], current: null, stopping: false, printed: '', mark: 0, held: [], answered: 0, looking: null, lookups: Promise.resolve(), pipe: pipe?.server };
         this.live.set(language, live);
         record.pid = place ? null : child.pid ?? null;
         const startMs = place ? this.limits.remoteStartTimeoutMs : this.limits.startTimeoutMs;
@@ -411,6 +454,8 @@ export class KernelHost {
         cell.state = 'running';
         cell.startedAt = now();
         live.record.state = 'busy';
+        cell.program = live.record.program ?? null;
+        cell.version = live.record.version;
         // A session on a server draws in its own temporary folder and sends each plot with its answer.
         live.child.stdin.write(JSON.stringify({ op: 'run', id: cell.cellId, number: cell.number, code: cell.code, plots: live.place ? null : await this.plots(), inline: !!live.place, maxPlots: this.limits.maxPlots, maxVariables: this.limits.maxVariables }) + '\n');
         this.changed();
@@ -437,7 +482,7 @@ export class KernelHost {
         const record = live.record, cell = live.current;
         if (msg.kind === 'ready') {
             clearTimeout(live.timer);
-            Object.assign(record, { state: 'idle', version: String(msg.version ?? ''), variables: msg.variables?.items ?? [], variablesOmitted: msg.variables?.omitted ?? 0, variablesAt: now(), host: typeof msg.host === 'string' ? msg.host.slice(0, 256) : null });
+            Object.assign(record, { state: 'idle', version: String(msg.version ?? ''), program: typeof msg.executable === 'string' && msg.executable ? this.named(live, msg.executable.slice(0, 1024)) : record.program ?? null, variables: msg.variables?.items ?? [], variablesOmitted: msg.variables?.omitted ?? 0, variablesAt: now(), host: typeof msg.host === 'string' ? msg.host.slice(0, 256) : null });
             if (live.place) {
                 live.remotePid = Number.isInteger(msg.pid) && msg.pid > 1 ? msg.pid : null;
                 record.pid = live.remotePid;
@@ -534,6 +579,7 @@ export class KernelHost {
         }
         if (this.live.get(record.language) === live)
             this.live.delete(record.language);
+        live.settle();
         this.changed();
     }
     // Interrupting a running cell stops it and leaves its session; a waiting cell is not run. A
@@ -761,6 +807,7 @@ const content = [
     'Results meant to last still go to files from a script, so they can be run again without the session.',
     'Sessions can also run on a server. kernel.places lists the places and where each language runs; kernel.place.set names one (the server, its folder there, and setup lines run there before a session starts) or chooses it for R or Python; kernel.place.check connects and reports R and Python there.',
     'kernel.servers lists the servers the person manages with serverctl and the skills bound to each: how that server is used (its environments, where heavy work goes, what to avoid there). Before you name a place on one or run code there, read the skills that apply with kernel.server.skill and follow them, for example in the place\'s setup lines. They guide the work on that server; they do not widen what you may do. A place on such a server is reached through serverctl, which holds its login; another server is reached with ssh.',
+    'The project\'s Python is the machine\'s python3 until you name another. When the work needs packages it lacks, make an environment in the project (python3 -m venv .venv or uv venv, then install into it) and pass interpreter: ".venv/bin/python" to kernel.run; later sessions of that language start with it too, and each cell records the program that ran it. A live session in which only you ran cells starts again with the program you name; once the person ran a cell in it, ask them to stop it first. Do not add another environment\'s packages to a running session\'s path.',
     'Pass place to kernel.run to start a session there. Paths in a session on a server are its folder\'s; kernel.place.list lists them and kernel.place.copy copies a file into the project under remote/<place>/.',
 ].join('\n');
 // What each view keeps in its props: the Notebook's form, and which value a value's view shows.

package/node_modules/@rho-workspace/plugin-kernel/dist/lineage.d.ts

@@ -57,10 +57,13 @@ export declare function lineage(cells: LineageCell[], values: string[], limits?:
     plots: number;
     files: number;
 }): Lineage;
-export declare function related(graph: Lineage, stepId: string): Set<string>;
-export declare function lanes(graph: Lineage): {
-    order: LineageStep[];
-    lane: Map<string, number>;
-    count: number;
-};
+export interface CellRelations {
+    reads: Map<string, Array<{
+        name: string;
+        from: LineageCell | null;
+    }>>;
+    readers: Map<string, Map<string, LineageCell[]>>;
+    maker: Map<string, LineageCell>;
+}
+export declare function cellRelations(cells: LineageCell[]): CellRelations;
 export declare function cellLabel(cell: LineageCell): string;

package/node_modules/@rho-workspace/plugin-kernel/dist/lineage.js

@@ -129,48 +129,25 @@ function place(steps, links) {
         step.nodes = step.nodes.map((n, i) => ({ n, i, at: toward(n.id) })).sort((a, b) => a.at - b.at || a.i - b.i).map(x => x.n);
     return layers;
 }
-// The steps a node comes from and leads to, through the links, for showing one path at a time.
-export function related(graph, stepId) {
-    const stepOfNode = new Map(graph.steps.flatMap(s => s.nodes.map(n => [n.id, s.id])));
-    const up = new Map(), down = new Map();
-    for (const link of graph.links) {
-        const from = stepOfNode.get(link.from);
-        up.set(link.to, [...up.get(link.to) ?? [], from]);
-        down.set(from, [...down.get(from) ?? [], link.to]);
-    }
-    const reach = (start, next) => {
-        const seen = new Set([start]), queue = [start];
-        while (queue.length)
-            for (const id of next.get(queue.pop()) ?? [])
-                if (!seen.has(id)) {
-                    seen.add(id);
-                    queue.push(id);
-                }
-        return seen;
-    };
-    return new Set([...reach(stepId, up), ...reach(stepId, down)]);
-}
-// The boxes in the order their cells ran (which is also an order in which each reads only from
-// boxes above it), and a lane in the margin for each value or file something read: from the line
-// that made it down past the boxes between, to each box that read it. Lanes whose spans do not
-// overlap share a place; lane 0 is nearest the boxes.
-export function lanes(graph) {
-    const order = [...graph.steps].sort((a, b) => (a.cell?.number ?? -1) - (b.cell?.number ?? -1));
-    const index = new Map(order.map((s, i) => [s.id, i])), stepOfNode = new Map(order.flatMap(s => s.nodes.map(n => [n.id, s.id])));
-    const spans = new Map();
-    for (const link of graph.links) {
-        const from = index.get(stepOfNode.get(link.from)), to = index.get(link.to), span = spans.get(link.from);
-        spans.set(link.from, { from, to: Math.max(to, span?.to ?? to) });
-    }
-    const ends = [], lane = new Map();
-    for (const [node, span] of [...spans].sort((a, b) => a[1].from - b[1].from || a[1].to - b[1].to)) {
-        let free = ends.findIndex(end => end <= span.from);
-        if (free < 0)
-            free = ends.length;
-        ends[free] = span.to;
-        lane.set(node, free);
+export function cellRelations(cells) {
+    const reads = new Map(), readers = new Map(), maker = new Map();
+    for (const cell of finished(cells)) {
+        reads.set(cell.cellId, (cell.used ?? []).map(name => {
+            const from = maker.get(name) ?? null;
+            if (from) {
+                let by = readers.get(from.cellId);
+                if (!by)
+                    readers.set(from.cellId, by = new Map());
+                by.set(name, [...by.get(name) ?? [], cell]);
+            }
+            return { name, from };
+        }));
+        for (const name of cell.removed ?? [])
+            maker.delete(name);
+        for (const name of cell.defined ?? [])
+            maker.set(name, cell);
     }
-    return { order, lane, count: ends.length };
+    return { reads, readers, maker };
 }
 // What a cell is called where it is named: its purpose (a script's lines), else its first line.
 export function cellLabel(cell) {

package/node_modules/@rho-workspace/plugin-kernel/dist/operations.js

@@ -3,9 +3,12 @@ import { cellId, cellSchema, changeId, copySchema, inspectStates, language, obje
 // Owner business contracts. Application project/authentication fields are separate.
 export const operationContracts = {
     // place names where a session that is not live yet starts ("local" is this machine); a cell
-    // naming another place than the live session's is refused.
+    // naming another place than the live session's is refused. interpreter names the program a
+    // session on this machine starts with, in a folder of the project (.venv/bin/python); the
+    // project keeps it for the language's later sessions. A cell naming another program than the
+    // live session's is refused.
     'kernel.run': {
-        inputSchema: obj({ language, code: { type: 'string', minLength: 1, maxLength: 65536 }, purpose: { type: 'string', maxLength: 200 }, changeId, waitMs: { type: 'integer', minimum: 0, maximum: 600000 }, place: placeRef }, ['language', 'code', 'changeId']),
+        inputSchema: obj({ language, code: { type: 'string', minLength: 1, maxLength: 65536 }, purpose: { type: 'string', maxLength: 200 }, changeId, waitMs: { type: 'integer', minimum: 0, maximum: 600000 }, place: placeRef, interpreter: { type: 'string', minLength: 1, maxLength: 1024 } }, ['language', 'code', 'changeId']),
         outputSchema: obj({ cell: cellSchema, session: sessionSchema }),
         requires: [], effect: 'native',
     },

package/node_modules/@rho-workspace/plugin-kernel/dist/script-flow.d.ts

@@ -0,0 +1,39 @@
+import type { Language } from './explore-code.js';
+import type { Lineage, LineageCell, LineageStep } from './lineage.js';
+export interface ScriptStep extends LineageStep {
+    cell: LineageCell;
+    from: number;
+    to: number;
+    changed: string[];
+    functions: string[];
+}
+export interface ScriptFlow extends Lineage {
+    steps: ScriptStep[];
+    quiet: number;
+    cut: number;
+    quietReads: Array<{
+        from: number;
+        to: number;
+        used: string[];
+        means?: string;
+    }>;
+    means: Map<string, string>;
+    outside: Array<{
+        name: string;
+        to: string;
+    }>;
+    tooLong: boolean;
+}
+export declare const scriptFlowLimits: {
+    bytes: number;
+    steps: number;
+};
+export declare function looksLikePath(s: string): boolean;
+export declare function markersAbove(lines: string[], line: number): Array<{
+    name: string | null;
+    text: string;
+}>;
+export declare function scriptFlow(text: string, language: Language, limits?: {
+    bytes: number;
+    steps: number;
+}, outside?: string[]): ScriptFlow;