@fnndsc/brasa 0.55.3 → 0.56.0

package/dist/builtins/berth/berthProcesses.d.ts

@@ -0,0 +1,32 @@
+/**
+ * One of the person's processes.
+ *
+ * @example
+ * ```ts
+ * const running: BerthProcess = { pid: 412, command: 'python train.py', open: ['/outgoing/model.pt'] };
+ * ```
+ */
+export interface BerthProcess {
+    /** Its process id. */
+    readonly pid: number;
+    /** Its command line, the words joined by spaces. */
+    readonly command: string;
+    /** The files it holds open under the folder asked about, by path. */
+    readonly open: readonly string[];
+}
+/**
+ * The person's processes still running in the berth, the session's own left
+ * out, each with the files it holds open under a folder.
+ *
+ * @param folder - The folder whose open files are said (the outgoing place).
+ * @param procRoot - The `/proc` folder; the system's by default.
+ * @param self - This process's id; the running process by default.
+ * @param uid - The person's user id; this process's by default.
+ * @returns The processes, by pid; empty when `/proc` is not there.
+ *
+ * @example
+ * ```ts
+ * processesOwn_list('/outgoing'); // [{ pid: 412, command: 'python train.py', open: ['/outgoing/model.pt'] }]
+ * ```
+ */
+export declare function processesOwn_list(folder: string, procRoot?: string, self?: number, uid?: number): BerthProcess[];

package/dist/builtins/berth/berthProcesses.js

@@ -0,0 +1,181 @@
+/**
+ * @file The person's processes still running in a berth, read from `/proc`,
+ * with the files each holds open under a folder.
+ *
+ * Inside a berth every process is the person's, so the processes that
+ * matter to a close are all of them but the session's own: this process,
+ * its parents up to PID 1, the terminals it runs for the console (a child
+ * whose environment carries `CHELL_TERMINAL` or `CHELL_CONSOLE`, as calypso
+ * starts them), and a shell such a terminal starts directly (`!`). Whatever
+ * runs under that shell is the person's work and is listed. A process of
+ * another user, or with no command line (a kernel thread, a zombie), is not
+ * listed.
+ *
+ * Key components:
+ * - BerthProcess: one process, its command and its open files under the folder.
+ * - processesOwn_list: the person's processes, the session's own left out.
+ *
+ * Typical usage:
+ * ```ts
+ * const running: BerthProcess[] = processesOwn_list('/outgoing');
+ * ```
+ *
+ * Dependencies: Node.js built-ins only; a Linux `/proc` (a berth's). Where
+ * `/proc` is not there, no process is listed.
+ *
+ * @module
+ */
+import { existsSync, readdirSync, readFileSync, readlinkSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+/** The environment marks of a console terminal calypso starts. */
+const TERMINAL_MARKS = ['CHELL_TERMINAL=', 'CHELL_CONSOLE='];
+/** The commands that are a shell a console terminal opens. */
+const SHELLS = new Set(['sh', 'bash', 'zsh', 'dash', 'ash', 'fish', 'ksh', 'tcsh', 'csh']);
+/**
+ * Reads a file of `/proc`, or nothing when the process is gone or the file cannot be read.
+ *
+ * @param path - The file.
+ * @returns Its text, or null.
+ */
+function procFile_read(path) {
+    try {
+        return readFileSync(path, 'latin1');
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Reads one process from `/proc/<pid>`.
+ *
+ * @param procRoot - The `/proc` folder.
+ * @param pid - The process.
+ * @returns The entry, or null when it is gone or unreadable.
+ */
+function procEntry_read(procRoot, pid) {
+    const stat = procFile_read(join(procRoot, String(pid), 'stat'));
+    if (stat === null)
+        return null;
+    // `comm` sits in parentheses and may hold spaces and parentheses itself:
+    // the fields after it start after the last `)`.
+    const open = stat.indexOf('(');
+    const close = stat.lastIndexOf(')');
+    if (open === -1 || close < open)
+        return null;
+    const fields = stat.slice(close + 2).split(' ');
+    const ppid = Number(fields[1]);
+    const cmdline = procFile_read(join(procRoot, String(pid), 'cmdline')) ?? '';
+    const environ = procFile_read(join(procRoot, String(pid), 'environ')) ?? '';
+    return {
+        pid,
+        ppid: Number.isFinite(ppid) ? ppid : 0,
+        name: stat.slice(open + 1, close),
+        argv: cmdline.split('\0').filter((word) => word !== ''),
+        terminal: environ.split('\0').some((pair) => TERMINAL_MARKS.some((mark) => pair.startsWith(mark))),
+    };
+}
+/**
+ * Every process of one user in `/proc`.
+ *
+ * @param procRoot - The `/proc` folder.
+ * @param uid - The user's id.
+ * @returns The processes, by pid.
+ */
+function procEntries_read(procRoot, uid) {
+    const entries = new Map();
+    if (!existsSync(procRoot))
+        return entries;
+    for (const name of readdirSync(procRoot)) {
+        if (!/^\d+$/.test(name))
+            continue;
+        const owner = statSync(join(procRoot, name), { throwIfNoEntry: false })?.uid;
+        if (owner !== uid)
+            continue;
+        const entry = procEntry_read(procRoot, Number(name));
+        if (entry !== null)
+            entries.set(entry.pid, entry);
+    }
+    return entries;
+}
+/**
+ * The session's own processes: this one, its parents up to PID 1, the
+ * console terminals it runs, and the shells those terminals start.
+ *
+ * @param entries - The user's processes.
+ * @param procRoot - The `/proc` folder, for parents of another user.
+ * @param self - This process's id.
+ * @returns Their ids.
+ */
+function sessionPids_find(entries, procRoot, self) {
+    const session = new Set([self]);
+    let parent = entries.get(self)?.ppid ?? procEntry_read(procRoot, self)?.ppid ?? 0;
+    while (parent > 0 && !session.has(parent)) {
+        session.add(parent);
+        parent = entries.get(parent)?.ppid ?? procEntry_read(procRoot, parent)?.ppid ?? 0;
+    }
+    const terminals = [...entries.values()]
+        .filter((entry) => entry.ppid === self && entry.terminal)
+        .map((entry) => entry.pid);
+    for (const terminal of terminals)
+        session.add(terminal);
+    for (const entry of entries.values()) {
+        if (terminals.includes(entry.ppid) && SHELLS.has(entry.name))
+            session.add(entry.pid);
+    }
+    return session;
+}
+/**
+ * The files a process holds open under a folder.
+ *
+ * @param procRoot - The `/proc` folder.
+ * @param pid - The process.
+ * @param folder - The folder, absolute.
+ * @returns Their paths, sorted; none when its descriptors cannot be read.
+ */
+function openFiles_list(procRoot, pid, folder) {
+    const fdDir = join(procRoot, String(pid), 'fd');
+    const prefix = folder.endsWith('/') ? folder : `${folder}/`;
+    let descriptors;
+    try {
+        descriptors = readdirSync(fdDir);
+    }
+    catch {
+        return [];
+    }
+    const open = new Set();
+    for (const descriptor of descriptors) {
+        try {
+            const target = readlinkSync(join(fdDir, descriptor));
+            if (target.startsWith(prefix))
+                open.add(target.replace(/ \(deleted\)$/, ''));
+        }
+        catch {
+            // A descriptor closed between the listing and the read holds nothing.
+        }
+    }
+    return [...open].sort();
+}
+/**
+ * The person's processes still running in the berth, the session's own left
+ * out, each with the files it holds open under a folder.
+ *
+ * @param folder - The folder whose open files are said (the outgoing place).
+ * @param procRoot - The `/proc` folder; the system's by default.
+ * @param self - This process's id; the running process by default.
+ * @param uid - The person's user id; this process's by default.
+ * @returns The processes, by pid; empty when `/proc` is not there.
+ *
+ * @example
+ * ```ts
+ * processesOwn_list('/outgoing'); // [{ pid: 412, command: 'python train.py', open: ['/outgoing/model.pt'] }]
+ * ```
+ */
+export function processesOwn_list(folder, procRoot = '/proc', self = process.pid, uid = process.getuid?.() ?? 0) {
+    const entries = procEntries_read(procRoot, uid);
+    const session = sessionPids_find(entries, procRoot, self);
+    return [...entries.values()]
+        .filter((entry) => !session.has(entry.pid) && entry.argv.length > 0)
+        .sort((a, b) => a.pid - b.pid)
+        .map((entry) => ({ pid: entry.pid, command: entry.argv.join(' '), open: openFiles_list(procRoot, entry.pid, folder) }));
+}
+//# sourceMappingURL=berthProcesses.js.map

package/dist/builtins/berth/berthProcesses.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"berthProcesses.js","sourceRoot":"","sources":["../../../src/builtins/berth/berthProcesses.ts"],"names":[],"mappings":"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"}

package/dist/builtins/berth/berthRecord.d.ts

@@ -0,0 +1,210 @@
+import type { AnchoredFile, BerthAnchor } from './berthState.js';
+/** The record's name, in the outgoing folder. */
+export declare const BERTH_RECORD_FILE: string;
+/**
+ * A file whose size differs from the size anchored.
+ *
+ * @example
+ * ```ts
+ * const resized: ResizedFile = { name: 'model.pt', anchored: 5, atClose: 6 };
+ * ```
+ */
+export interface ResizedFile {
+    /** Its name relative to the anchor. */
+    readonly name: string;
+    /** Its size when anchored, in bytes. */
+    readonly anchored: number;
+    /** Its size in ChRIS at the close, in bytes. */
+    readonly atClose: number;
+}
+/**
+ * What differs between an anchor's files and what ChRIS holds at the close.
+ *
+ * @example
+ * ```ts
+ * const changes: AnchorChanges = { added: ['extra.pt'], removed: [], resized: [], unreadable: null };
+ * ```
+ */
+export interface AnchorChanges {
+    /** Files ChRIS holds that were not anchored. */
+    readonly added: readonly string[];
+    /** Files anchored that ChRIS does not hold at the close. */
+    readonly removed: readonly string[];
+    /** Files whose size differs. */
+    readonly resized: readonly ResizedFile[];
+    /** Why ChRIS could not be read for the comparison; null when it was read. */
+    readonly unreadable: string | null;
+}
+/**
+ * One anchor as the record holds it: the anchor, and what changed since.
+ *
+ * @example
+ * ```ts
+ * const anchor: RecordAnchor = { name: 'weights', path: '/home/alice/uploads/weights', node: null, feed: null, files: [], anchoredAt: '…', changes: null };
+ * ```
+ */
+export interface RecordAnchor extends BerthAnchor {
+    /** What differs in ChRIS since the anchor; null for an anchor under a node, which does not change. */
+    readonly changes: AnchorChanges | null;
+}
+/**
+ * Where the work's node goes.
+ *
+ * @example
+ * ```ts
+ * const child: BerthPlacement = { kind: 'child', by: 'anchors', parent: 41, parentName: 'pl-fshack_41', feed: 5, anchor: null };
+ * const fresh: BerthPlacement = { kind: 'newFeed', by: '--newfeed', name: 'berth work', inputs: ['/home/alice/uploads/weights'] };
+ * ```
+ */
+export type BerthPlacement = PlacementChild | PlacementNewFeed;
+/** What decided a placement: the anchors themselves, or the flag given. */
+export type PlacementCause = 'anchors' | '--infeed' | '--newfeed';
+/** The work as a child of a node of the person's feeds. */
+export interface PlacementChild {
+    /** A child of a node. */
+    readonly kind: 'child';
+    /** What decided it. */
+    readonly by: PlacementCause;
+    /** The parent plugin instance. */
+    readonly parent: number;
+    /** The parent's folder name, `pl-fshack_41`. */
+    readonly parentName: string;
+    /** The parent's feed. */
+    readonly feed: number | null;
+    /** The anchor `--infeed` named; null when the anchors decided. */
+    readonly anchor: string | null;
+}
+/** The work in a new feed. */
+export interface PlacementNewFeed {
+    /** A new feed. */
+    readonly kind: 'newFeed';
+    /** What decided it. */
+    readonly by: PlacementCause;
+    /** The feed's name. */
+    readonly name: string;
+    /** The ChRIS paths its `pl-dircopy` root copies; empty when the root is the work itself. */
+    readonly inputs: readonly string[];
+}
+/**
+ * The node made, once the close attached the work.
+ *
+ * @example
+ * ```ts
+ * const attached: BerthAttachment = { feed: 12, node: 58, plugin: 'pl-dsdircopy', root: 57 };
+ * ```
+ */
+export interface BerthAttachment {
+    /** The feed the node is in; null when CUBE did not say. */
+    readonly feed: number | null;
+    /** The work's plugin instance. */
+    readonly node: number;
+    /** Its plugin. */
+    readonly plugin: string;
+    /** The new feed's root, when the close made one under the work; else null. */
+    readonly root: number | null;
+}
+/**
+ * The source the work was made from: the git repository holding the folder the session runs in.
+ *
+ * @example
+ * ```ts
+ * const source: BerthSource = { repository: '/home/alice/src/seg', commit: '3f2a…', dirty: false };
+ * ```
+ */
+export interface BerthSource {
+    /** The repository's top folder. */
+    readonly repository: string;
+    /** The commit checked out. */
+    readonly commit: string;
+    /** Whether the working tree differs from the commit. */
+    readonly dirty: boolean;
+}
+/**
+ * `berth.json`.
+ *
+ * @example
+ * ```ts
+ * const record: BerthRecord = {
+ *   version: 1, who: 'alice', session: 'berth-alice', image: null, source: null, closedAt: '2026-11-14T10:00:00.000Z',
+ *   title: 'berth work', anchors: [], outgoing: '/outgoing', folder: '/home/alice/berth/0b6c…',
+ *   placement: { kind: 'newFeed', by: 'anchors', name: 'berth work', inputs: [] }, attached: null,
+ * };
+ * ```
+ */
+export interface BerthRecord {
+    /** The record's format version. */
+    readonly version: number;
+    /** The person, by CUBE user name. */
+    readonly who: string;
+    /** The berth session: the berth's host name. */
+    readonly session: string;
+    /** The berth's image, as the berth names it; null when it does not. */
+    readonly image: string | null;
+    /** The source commit; null when the session's folder is in no git repository. */
+    readonly source: BerthSource | null;
+    /** When the close ran. */
+    readonly closedAt: string;
+    /** The work node's title. */
+    readonly title: string;
+    /** Every anchor, with what changed since. */
+    readonly anchors: readonly RecordAnchor[];
+    /** The outgoing folder returned. */
+    readonly outgoing: string;
+    /** The person's CUBE files folder it was uploaded to. */
+    readonly folder: string;
+    /** Where the node goes. */
+    readonly placement: BerthPlacement;
+    /** The node made; null until the close attached it. */
+    readonly attached: BerthAttachment | null;
+}
+/**
+ * What differs between the files anchored and the files ChRIS holds at the close, by name and size.
+ *
+ * @param anchored - The files the anchor downloaded.
+ * @param atClose - The files ChRIS holds at the anchor's path at the close.
+ * @returns The files added, removed and resized, each sorted by name.
+ *
+ * @example
+ * ```ts
+ * anchorChanges_compare([{ name: 'a', size: 1 }, { name: 'b', size: 2 }], [{ name: 'b', size: 3 }, { name: 'c', size: 1 }]);
+ * // { added: ['c'], removed: ['a'], resized: [{ name: 'b', anchored: 2, atClose: 3 }], unreadable: null }
+ * ```
+ */
+export declare function anchorChanges_compare(anchored: readonly AnchoredFile[], atClose: readonly AnchoredFile[]): AnchorChanges;
+/**
+ * Whether a comparison found anything different, or could not be made.
+ *
+ * @param changes - The comparison.
+ * @returns True when a file was added, removed or resized, or ChRIS could not be read.
+ *
+ * @example
+ * ```ts
+ * anchorChanges_any({ added: [], removed: [], resized: [], unreadable: null }); // false
+ * ```
+ */
+export declare function anchorChanges_any(changes: AnchorChanges): boolean;
+/**
+ * The git commit a folder is at, when it is in a repository.
+ *
+ * @param folder - The folder the session runs in.
+ * @returns The repository, its commit and whether its tree differs; null outside a repository, or one with no commit.
+ *
+ * @example
+ * ```ts
+ * berthSource_read('/home/alice/src/seg'); // { repository: '/home/alice/src/seg', commit: '3f2a…', dirty: false }
+ * ```
+ */
+export declare function berthSource_read(folder: string): BerthSource | null;
+/**
+ * Writes the record into a folder as `berth.json`.
+ *
+ * @param folder - The outgoing folder.
+ * @param record - The record.
+ * @returns The file written.
+ *
+ * @example
+ * ```ts
+ * berthRecord_write('/outgoing', record); // '/outgoing/berth.json'
+ * ```
+ */
+export declare function berthRecord_write(folder: string, record: BerthRecord): string;

package/dist/builtins/berth/berthRecord.js

@@ -0,0 +1,130 @@
+/**
+ * @file `berth.json`, the record a close writes into the outgoing folder and
+ * returns with the work: who, every anchor with its ChRIS path, node, feed,
+ * what was downloaded and what changed since, the berth session, the source
+ * commit, the image, the time, and where the node goes.
+ *
+ * The record travels in the data, so a copy or a download of the node keeps
+ * it. It is written before the upload with the placement the close decided,
+ * and written again in the berth once the node is made, with the node's
+ * feed and id.
+ *
+ * Key components:
+ * - BERTH_RECORD_FILE: the record's name, `berth.json`.
+ * - BerthRecord, RecordAnchor, AnchorChanges, BerthPlacement, BerthAttachment, BerthSource: its shape.
+ * - anchorChanges_compare: what differs between the files anchored and the files ChRIS holds at the close.
+ * - anchorChanges_any: whether anything differs.
+ * - berthSource_read: the git commit of a folder, when it is in a repository.
+ * - berthRecord_write: writes the record into a folder.
+ *
+ * Typical usage:
+ * ```ts
+ * const changes: AnchorChanges = anchorChanges_compare(anchor.files, atClose);
+ * berthRecord_write('/outgoing', record);
+ * ```
+ *
+ * Dependencies: Node.js built-ins; `git` on the path for the source commit
+ * (none when it is absent). Times are ISO 8601 strings, sizes bytes.
+ *
+ * @module
+ */
+import { execFileSync } from 'node:child_process';
+import { writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+/** The record's name, in the outgoing folder. */
+export const BERTH_RECORD_FILE = 'berth.json';
+/** The record's format version. */
+const BERTH_RECORD_VERSION = 1;
+/** How long `git` may take to say the commit, in milliseconds. */
+const GIT_TIMEOUT_MS = 5_000;
+/**
+ * What differs between the files anchored and the files ChRIS holds at the close, by name and size.
+ *
+ * @param anchored - The files the anchor downloaded.
+ * @param atClose - The files ChRIS holds at the anchor's path at the close.
+ * @returns The files added, removed and resized, each sorted by name.
+ *
+ * @example
+ * ```ts
+ * anchorChanges_compare([{ name: 'a', size: 1 }, { name: 'b', size: 2 }], [{ name: 'b', size: 3 }, { name: 'c', size: 1 }]);
+ * // { added: ['c'], removed: ['a'], resized: [{ name: 'b', anchored: 2, atClose: 3 }], unreadable: null }
+ * ```
+ */
+export function anchorChanges_compare(anchored, atClose) {
+    const before = new Map(anchored.map((file) => [file.name, file.size]));
+    const after = new Map(atClose.map((file) => [file.name, file.size]));
+    const byName = (a, b) => a.localeCompare(b);
+    const added = [...after.keys()].filter((name) => !before.has(name)).sort(byName);
+    const removed = [...before.keys()].filter((name) => !after.has(name)).sort(byName);
+    const resized = [...before.entries()]
+        .filter(([name, size]) => after.has(name) && after.get(name) !== size)
+        .map(([name, size]) => ({ name, anchored: size, atClose: after.get(name) ?? 0 }))
+        .sort((a, b) => byName(a.name, b.name));
+    return { added, removed, resized, unreadable: null };
+}
+/**
+ * Whether a comparison found anything different, or could not be made.
+ *
+ * @param changes - The comparison.
+ * @returns True when a file was added, removed or resized, or ChRIS could not be read.
+ *
+ * @example
+ * ```ts
+ * anchorChanges_any({ added: [], removed: [], resized: [], unreadable: null }); // false
+ * ```
+ */
+export function anchorChanges_any(changes) {
+    return changes.added.length + changes.removed.length + changes.resized.length > 0 || changes.unreadable !== null;
+}
+/**
+ * Runs `git` in a folder.
+ *
+ * @param folder - The folder.
+ * @param args - The words after `git`.
+ * @returns What it printed, trimmed; null when it failed or is not there.
+ */
+function git_ask(folder, args) {
+    try {
+        return execFileSync('git', ['-C', folder, ...args], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: GIT_TIMEOUT_MS }).trim();
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The git commit a folder is at, when it is in a repository.
+ *
+ * @param folder - The folder the session runs in.
+ * @returns The repository, its commit and whether its tree differs; null outside a repository, or one with no commit.
+ *
+ * @example
+ * ```ts
+ * berthSource_read('/home/alice/src/seg'); // { repository: '/home/alice/src/seg', commit: '3f2a…', dirty: false }
+ * ```
+ */
+export function berthSource_read(folder) {
+    const repository = git_ask(folder, ['rev-parse', '--show-toplevel']);
+    const commit = git_ask(folder, ['rev-parse', 'HEAD']);
+    if (repository === null || commit === null || commit === '')
+        return null;
+    const status = git_ask(folder, ['status', '--porcelain']);
+    return { repository, commit, dirty: status !== null && status !== '' };
+}
+/**
+ * Writes the record into a folder as `berth.json`.
+ *
+ * @param folder - The outgoing folder.
+ * @param record - The record.
+ * @returns The file written.
+ *
+ * @example
+ * ```ts
+ * berthRecord_write('/outgoing', record); // '/outgoing/berth.json'
+ * ```
+ */
+export function berthRecord_write(folder, record) {
+    const file = join(folder, BERTH_RECORD_FILE);
+    writeFileSync(file, `${JSON.stringify({ ...record, version: BERTH_RECORD_VERSION }, null, 2)}\n`, { mode: 0o644 });
+    return file;
+}
+//# sourceMappingURL=berthRecord.js.map

package/dist/builtins/berth/berthRecord.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"berthRecord.js","sourceRoot":"","sources":["../../../src/builtins/berth/berthRecord.ts"],"names":[],"mappings":"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"}