@fnndsc/brasa 0.23.2 → 0.24.0

package/dist/builtins/res/record.d.ts

@@ -0,0 +1,49 @@
+import { CommandEnvelope } from '@fnndsc/cumin';
+/** The model kind under which a finished recording travels. */
+export declare const RECORD_MODEL_KIND: string;
+/** What a recording turned into. */
+export interface RecordedManifest {
+    /** Where it was written. */
+    path: string;
+    /** How many lines it holds. */
+    lines: number;
+    /** The parameters it was given, and the literal each replaced. */
+    params: Array<{
+        name: string;
+        was: string;
+    }>;
+    /** How long the recording ran. */
+    elapsedMs: number;
+}
+/**
+ * Offers parameters for the identifiers a recording carries.
+ *
+ * @param lines - The captured lines.
+ * @returns The lines with identifiers replaced, and what was replaced.
+ */
+export declare function identifiers_offer(lines: string[]): {
+    lines: string[];
+    params: Array<{
+        name: string;
+        was: string;
+    }>;
+};
+/**
+ * Renders the manifest a recording became.
+ *
+ * @param name - What to call it.
+ * @param lines - The captured lines, already parameterized.
+ * @param params - The parameters offered.
+ * @returns The file's text.
+ */
+export declare function manifest_render(name: string, lines: string[], params: Array<{
+    name: string;
+    was: string;
+}>): string;
+/**
+ * Builtin handler for the `record` command.
+ *
+ * @param args - Parsed command arguments.
+ * @returns An envelope reporting what the recorder is doing, or what it wrote.
+ */
+export declare function builtin_record(args: string[]): Promise<CommandEnvelope>;

package/dist/builtins/res/record.js

@@ -0,0 +1,150 @@
+/**
+ * @file Builtin record command: writing a session down as a manifest.
+ *
+ * Subcommands: start, stop, status.
+ *
+ * Every verb lowers to a line the operator could have typed, so a session's
+ * line history is very nearly a manifest already — a press on a surface and
+ * a line at a console arrive at the same place, and the recorder sits there.
+ * That is why this costs almost nothing: the lowering was already the law.
+ *
+ * @module
+ */
+import chalk from 'chalk';
+import { envelope_ok, envelope_error } from '@fnndsc/cumin';
+import { files_touch as chefs_touch_cmd } from '@fnndsc/chili/commands/fs/touch.js';
+import { files_mkdir as chefs_mkdir_cmd } from '@fnndsc/chili/commands/fs/mkdir.js';
+import path from 'path';
+import { commandArgs_process, path_resolve } from '../utils.js';
+import { recorder_start, recorder_state, recorder_stop, } from '../../session/recorder.js';
+/** The model kind under which a finished recording travels. */
+export const RECORD_MODEL_KIND = 'manifest.recorded';
+/**
+ * Literals worth offering as parameters.
+ *
+ * A recording is personal until its identifiers come out of it: the MRN and
+ * the accession are exactly what the next person has to change, and they are
+ * the two a PACS line wears on its face. Nothing else is guessed at — a
+ * parameter the author did not want is worse than one they have to add.
+ */
+const IDENTIFIER_PATTERNS = [
+    { criterion: 'PatientID', param: 'MRN' },
+    { criterion: 'AccessionNumber', param: 'ACC' },
+    { criterion: 'PatientName', param: 'PATIENT' },
+];
+/**
+ * Offers parameters for the identifiers a recording carries.
+ *
+ * @param lines - The captured lines.
+ * @returns The lines with identifiers replaced, and what was replaced.
+ */
+export function identifiers_offer(lines) {
+    const params = [];
+    const taken = new Map();
+    const rewritten = lines.map((line) => {
+        let text = line;
+        for (const { criterion, param } of IDENTIFIER_PATTERNS) {
+            // The value stops at an underscore or a slash: a query's projection
+            // folder is `PatientID:1279049_qid:3125_owner`, and a value that ran on
+            // to the end of the word would parameterize the query id too, so the
+            // same MRN in a path and in a query would read as two patients.
+            const pattern = new RegExp(`${criterion}:([^\\s'"/_]+)`, 'g');
+            text = text.replace(pattern, (match, value) => {
+                const held = taken.get(match);
+                if (held !== undefined)
+                    return `${criterion}:\${${held}}`;
+                // A second distinct value for the same criterion gets its own name,
+                // or a workflow over two patients would collapse into one.
+                const name = taken.size === 0 || ![...taken.values()].includes(param)
+                    ? param
+                    : `${param}_${taken.size + 1}`;
+                taken.set(match, name);
+                params.push({ name, was: value });
+                return `${criterion}:\${${name}}`;
+            });
+        }
+        return text;
+    });
+    return { lines: rewritten, params };
+}
+/**
+ * Renders the manifest a recording became.
+ *
+ * @param name - What to call it.
+ * @param lines - The captured lines, already parameterized.
+ * @param params - The parameters offered.
+ * @returns The file's text.
+ */
+export function manifest_render(name, lines, params) {
+    const header = [
+        `@name         ${name}`,
+        `@description  Recorded from a session on ${new Date().toISOString().slice(0, 10)}.`,
+    ];
+    for (const param of params)
+        header.push(`@param        ${param.name} = ${param.was}`);
+    return `${[...header, '', ...lines].join('\n')}\n`;
+}
+/**
+ * Builtin handler for the `record` command.
+ *
+ * @param args - Parsed command arguments.
+ * @returns An envelope reporting what the recorder is doing, or what it wrote.
+ */
+export async function builtin_record(args) {
+    const parsed = commandArgs_process(args);
+    const subcommand = parsed._[0];
+    if (subcommand === 'start') {
+        const target = parsed._[1];
+        if (target === undefined) {
+            process.exitCode = 1;
+            return envelope_error('', undefined, `${chalk.red('Usage: record start <manifest>')}\n`);
+        }
+        const state = recorder_state();
+        if (state.target !== null) {
+            process.exitCode = 1;
+            return envelope_error('', undefined, `${chalk.red(`record: already recording to ${state.target} — stop it first.`)}\n`);
+        }
+        const resolved = await path_resolve(target);
+        recorder_start(resolved);
+        return envelope_ok(`${chalk.green(`record: recording to ${resolved}. Do the work; \`record stop\` writes it.`)}\n`);
+    }
+    if (subcommand === 'stop') {
+        const held = recorder_stop();
+        if (held === null) {
+            process.exitCode = 1;
+            return envelope_error('', undefined, `${chalk.red('record: nothing is recording.')}\n`);
+        }
+        if (held.lines.length === 0) {
+            return envelope_ok(`${chalk.yellow(`record: nothing to write — the session ran no lines while recording.`)}\n`);
+        }
+        const { lines, params } = identifiers_offer(held.lines);
+        const name = path.posix.basename(held.target).replace(/\.[^.]+$/, '');
+        await chefs_mkdir_cmd(path.posix.dirname(held.target));
+        const written = await chefs_touch_cmd(held.target, {
+            withContents: manifest_render(name, lines, params),
+        });
+        if (!written) {
+            process.exitCode = 1;
+            return envelope_error('', undefined, `${chalk.red(`record: could not write ${held.target}.`)}\n`);
+        }
+        const recorded = {
+            path: held.target,
+            lines: lines.length,
+            params,
+            elapsedMs: held.elapsedMs,
+        };
+        const offered = params.length === 0
+            ? ''
+            : `${chalk.gray(`  offered ${params.length} param${params.length === 1 ? '' : 's'}: `)}${params.map((param) => `${param.was} → \${${param.name}}`).join(', ')}\n`;
+        return envelope_ok(`${chalk.green(`record: wrote ${held.target} · ${lines.length} line${lines.length === 1 ? '' : 's'}`)}\n${offered}`, { kind: RECORD_MODEL_KIND, data: recorded });
+    }
+    if (subcommand === undefined || subcommand === 'status') {
+        const state = recorder_state();
+        if (state.target === null)
+            return envelope_ok(`${chalk.gray('Nothing is recording.')}\n`);
+        return envelope_ok(`${chalk.green(`Recording to ${state.target}`)} ${chalk.gray(`· ${state.lines} line${state.lines === 1 ? '' : 's'} · ${Math.round(state.elapsedMs / 1000)}s`)}\n`);
+    }
+    process.exitCode = 1;
+    return envelope_error('', undefined, `${chalk.red(`Unknown subcommand: ${subcommand}. Usage: record <start|stop|status>`)}\n`);
+}
+//# sourceMappingURL=record.js.map

package/dist/builtins/res/record.js.map

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

package/dist/builtins/res/runWait.d.ts

@@ -0,0 +1,49 @@
+/** Statuses a run does not leave. */
+export declare const RUN_TERMINAL_STATUSES: ReadonlySet<string>;
+/** How a wait ended. */
+export type RunSettlementOutcome = 'settled' | 'detached' | 'unreachable';
+/** What a wait found out. */
+export interface RunSettlement {
+    /** The runs waited on. */
+    instanceIDs: number[];
+    /** Each run's status: terminal when settled, last seen otherwise. */
+    statuses: Map<number, string>;
+    /** How the wait ended. */
+    outcome: RunSettlementOutcome;
+    /** How many runs ended in a status that is not success. */
+    failed: number;
+    /** How long the wait lasted. */
+    elapsedMs: number;
+}
+/** How often a wait asks, for a caller that knows better than the default. */
+export interface RunWaitCadence {
+    /** Milliseconds between asks. Both windows collapse to this when given. */
+    pollMs?: number;
+}
+/**
+ * Waits for every given run to reach a status it does not leave.
+ *
+ * @param instanceIDs - The plugin instances to wait on.
+ * @param label - What to call the work in progress and readouts.
+ * @param cadence - How often to ask, when the default rhythm is wrong.
+ * @returns How the wait ended, and the statuses it ended on.
+ */
+export declare function runs_awaitSettled(instanceIDs: number[], label: string, cadence?: RunWaitCadence): Promise<RunSettlement>;
+/**
+ * Renders how long a wait lasted, the way an operator says it.
+ *
+ * @param ms - Elapsed milliseconds.
+ * @returns A short duration, such as `2m14s`.
+ */
+export declare function elapsed_render(ms: number): string;
+/**
+ * Renders what a wait found, in the operator's terms.
+ *
+ * A detached wait says how to get back to the work, because the run is still
+ * going and the handle is the only way to reach it.
+ *
+ * @param settlement - What the wait found.
+ * @param label - What the work is called.
+ * @returns The line to print.
+ */
+export declare function settlement_render(settlement: RunSettlement, label: string): string;

package/dist/builtins/res/runWait.js

@@ -0,0 +1,193 @@
+/**
+ * @file Waiting for scheduled work to settle.
+ *
+ * A scheduled run used to return the moment CUBE accepted it, which reads as
+ * completion and is not: the next line in a script runs against output that
+ * does not exist yet, and the only way to sequence work was a sleep, which is
+ * a lie about time. A verb that starts work therefore waits for it, and
+ * `--detach` is how an operator asks for the handle instead.
+ *
+ * Waiting holds the LINE, never the session. Progress goes out on the
+ * progress channel while the wait runs, so a surface shows the work moving
+ * and other panes keep refreshing; a cancellation (Esc at a surface, Ctrl-C
+ * at a console) DETACHES rather than kills — the run continues and its
+ * handle is printed, which is what `--detach` would have given, asked for
+ * later.
+ *
+ * A pipeline schedules several nodes at once, so a wait is over a SET: it
+ * ends when every node it was given has reached a status it does not leave.
+ *
+ * @module
+ */
+import chalk from 'chalk';
+import { jobs_statusBatch } from '@fnndsc/salsa';
+import { sink_get } from '../../core/sink.js';
+import { commandCancellation_enable, commandCancellation_signalGet } from '../../core/cancellation.js';
+/** Statuses a run does not leave. */
+export const RUN_TERMINAL_STATUSES = new Set([
+    'finishedSuccessfully',
+    'finishedWithError',
+    'cancelled',
+]);
+/** First seconds are polled briskly; a long run is not worth the traffic. */
+const POLL_FAST_MS = 2000;
+/** What the interval settles to once the work is clearly not instant. */
+const POLL_SLOW_MS = 5000;
+/** When the interval stretches. */
+const POLL_BRISK_WINDOW_MS = 30000;
+/** Consecutive unanswered status asks before the wait gives up on knowing. */
+const STATUS_MISSES_MAX = 5;
+/**
+ * Sleeps, unless the command is cancelled first.
+ *
+ * @param ms - How long to wait.
+ * @param signal - The foreground command's abort signal, when there is one.
+ * @returns True when the sleep completed, false when cancellation cut it short.
+ */
+async function pause_take(ms, signal) {
+    if (signal?.aborted === true)
+        return false;
+    return await new Promise((resolve) => {
+        const onAbort = () => {
+            clearTimeout(timer);
+            resolve(false);
+        };
+        const timer = setTimeout(() => {
+            signal?.removeEventListener('abort', onAbort);
+            resolve(true);
+        }, ms);
+        signal?.addEventListener('abort', onAbort, { once: true });
+    });
+}
+/**
+ * Says how the wait is going, on the channel progress travels on.
+ *
+ * @param label - What to call the work on a surface.
+ * @param settled - How many of the runs have finished.
+ * @param total - How many runs the wait covers.
+ * @param phase - Whether the work is still going, done, or failed.
+ */
+function runProgress_emit(label, settled, total, phase) {
+    sink_get().progress_write({
+        operation: 'workflow',
+        kind: 'workflow',
+        phase,
+        label,
+        current: settled,
+        total,
+        percent: total > 0 ? Math.min(100, (settled / total) * 100) : undefined,
+        unit: 'jobs',
+        status: phase === 'working' ? 'running' : (phase === 'complete' ? 'done' : 'error'),
+    });
+}
+/**
+ * Counts the runs that have reached a terminal status, and those that failed.
+ *
+ * @param statuses - Status by instance id.
+ * @returns How many are settled, and how many of those did not succeed.
+ */
+function settlement_count(statuses) {
+    let settled = 0;
+    let failed = 0;
+    for (const status of statuses.values()) {
+        if (!RUN_TERMINAL_STATUSES.has(status))
+            continue;
+        settled += 1;
+        if (status !== 'finishedSuccessfully')
+            failed += 1;
+    }
+    return { settled, failed };
+}
+/**
+ * Waits for every given run to reach a status it does not leave.
+ *
+ * @param instanceIDs - The plugin instances to wait on.
+ * @param label - What to call the work in progress and readouts.
+ * @param cadence - How often to ask, when the default rhythm is wrong.
+ * @returns How the wait ended, and the statuses it ended on.
+ */
+export async function runs_awaitSettled(instanceIDs, label, cadence = {}) {
+    const started = Date.now();
+    const statuses = new Map(instanceIDs.map((id) => [id, 'scheduled']));
+    if (instanceIDs.length === 0) {
+        return { instanceIDs, statuses, outcome: 'settled', failed: 0, elapsedMs: 0 };
+    }
+    // A wait is exactly the kind of work a cancellation should reach.
+    commandCancellation_enable();
+    const signal = commandCancellation_signalGet();
+    let misses = 0;
+    for (;;) {
+        const read = await jobs_statusBatch(instanceIDs);
+        if (read.size === 0) {
+            // One unanswered ask is a network hiccup, not a verdict on the work.
+            misses += 1;
+            if (misses >= STATUS_MISSES_MAX) {
+                return { instanceIDs, statuses, outcome: 'unreachable', failed: 0, elapsedMs: Date.now() - started };
+            }
+        }
+        else {
+            misses = 0;
+            for (const [id, status] of read)
+                statuses.set(id, status);
+            const { settled, failed } = settlement_count(statuses);
+            if (settled === instanceIDs.length) {
+                runProgress_emit(label, settled, instanceIDs.length, failed > 0 ? 'failed' : 'complete');
+                return { instanceIDs, statuses, outcome: 'settled', failed, elapsedMs: Date.now() - started };
+            }
+            runProgress_emit(label, settled, instanceIDs.length, 'working');
+        }
+        const elapsed = Date.now() - started;
+        const interval = cadence.pollMs
+            ?? (elapsed < POLL_BRISK_WINDOW_MS ? POLL_FAST_MS : POLL_SLOW_MS);
+        const slept = await pause_take(interval, signal);
+        if (!slept) {
+            const { failed } = settlement_count(statuses);
+            return { instanceIDs, statuses, outcome: 'detached', failed, elapsedMs: Date.now() - started };
+        }
+    }
+}
+/**
+ * Renders how long a wait lasted, the way an operator says it.
+ *
+ * @param ms - Elapsed milliseconds.
+ * @returns A short duration, such as `2m14s`.
+ */
+export function elapsed_render(ms) {
+    const seconds = Math.round(ms / 1000);
+    if (seconds < 60)
+        return `${seconds}s`;
+    const minutes = Math.floor(seconds / 60);
+    return `${minutes}m${`${seconds % 60}`.padStart(2, '0')}s`;
+}
+/**
+ * Renders what a wait found, in the operator's terms.
+ *
+ * A detached wait says how to get back to the work, because the run is still
+ * going and the handle is the only way to reach it.
+ *
+ * @param settlement - What the wait found.
+ * @param label - What the work is called.
+ * @returns The line to print.
+ */
+export function settlement_render(settlement, label) {
+    const took = elapsed_render(settlement.elapsedMs);
+    const handles = settlement.instanceIDs.join(', ');
+    if (settlement.outcome === 'detached') {
+        return chalk.yellow(`${label}: detached after ${took} — the run continues. Instance ${handles}; follow it with \`plugininstance list\` or the feed's graph.`);
+    }
+    if (settlement.outcome === 'unreachable') {
+        return chalk.yellow(`${label}: lost touch with CUBE after ${took} — the run may still be going. Instance ${handles}.`);
+    }
+    if (settlement.failed > 0) {
+        const failedIds = [...settlement.statuses.entries()]
+            .filter(([, status]) => status !== 'finishedSuccessfully')
+            .map(([id, status]) => `${id} ${status}`)
+            .join(', ');
+        return chalk.red(`${label}: finished with errors after ${took} — ${failedIds}`);
+    }
+    const nodes = settlement.instanceIDs.length === 1
+        ? `instance ${handles}`
+        : `${settlement.instanceIDs.length} nodes`;
+    return chalk.green(`${label}: finished successfully in ${took} (${nodes})`);
+}
+//# sourceMappingURL=runWait.js.map

package/dist/builtins/res/runWait.js.map

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

package/dist/builtins/sys/weather.d.ts

@@ -0,0 +1,132 @@
+/**
+ * @file Builtin weather.
+ *
+ * Reports the weather at a place — the current conditions and the next few
+ * days — from Open-Meteo, which needs no key and no account. A place is
+ * geocoded by name through the same service, so `weather Boston` and
+ * `weather Cape Town` both work, and a bare `weather` asks about Boston,
+ * where the lab is — in metric, as the lab reads, unless `--units imperial`.
+ *
+ * The report is a kernel fact like `date` or `fortune`: it renders once and
+ * every surface shows the same text, and the typed model beneath it carries
+ * the numbers for a surface that wants to draw them differently. The
+ * network reached is the daemon's, so a host that cannot see the internet
+ * says so in one line rather than hanging.
+ *
+ * @module
+ */
+import { CommandEnvelope } from '@fnndsc/cumin';
+/** Where `weather` looks when given no place. */
+export declare const WEATHER_DEFAULT_PLACE: string;
+/** The two unit systems `--units` takes. */
+export type WeatherUnits = 'metric' | 'imperial';
+/** The system used when none is asked for: the lab reports in metric. */
+export declare const WEATHER_UNITS_DEFAULT: WeatherUnits;
+/**
+ * A fetch the report goes through — the global one in a daemon, a stub in
+ * a test.
+ */
+export type WeatherFetch = (url: string, init?: RequestInit) => Promise<Response>;
+/** A place the geocoder answered with. */
+export interface WeatherPlace {
+    name: string;
+    region: string;
+    country: string;
+    latitude: number;
+    longitude: number;
+    timezone: string;
+}
+/** The conditions now. */
+export interface WeatherNow {
+    time: string;
+    temperature: number;
+    apparent: number;
+    humidity: number;
+    code: number;
+    condition: string;
+    windSpeed: number;
+    windDirection: string;
+}
+/** One day of the forecast. */
+export interface WeatherDay {
+    date: string;
+    low: number;
+    high: number;
+    code: number;
+    condition: string;
+}
+/** The report, as the model beneath the rendered text. */
+export interface WeatherReport {
+    place: WeatherPlace;
+    units: 'F' | 'C';
+    now: WeatherNow;
+    days: WeatherDay[];
+}
+/** The words a call line was parsed into. */
+interface WeatherArgs {
+    place: string;
+    units: WeatherUnits;
+    days: number;
+}
+/**
+ * Words a WMO weather code.
+ *
+ * @param code - The code Open-Meteo reported.
+ * @returns The condition in words; an unknown code says so with its number.
+ */
+export declare function condition_ofCode(code: number): string;
+/**
+ * Names a wind direction on the eight-point compass.
+ *
+ * @param degrees - Where the wind comes from, degrees clockwise from north.
+ * @returns The compass point.
+ */
+export declare function compass_ofDegrees(degrees: number): string;
+/**
+ * Parses the call line: a place in as many words as it takes, `--units`
+ * for the system, `-d N` for the days shown. Any other flag is refused by
+ * name.
+ *
+ * @param args - The words after `weather`.
+ * @returns The parsed call, or the refusal to print.
+ */
+export declare function weatherArgs_parse(args: string[]): WeatherArgs | string;
+/**
+ * Finds a place by name.
+ *
+ * @param fetchFn - The fetch to go through.
+ * @param name - The place as the operator typed it.
+ * @returns The first place the geocoder offers, or null when it offers none.
+ */
+export declare function place_find(fetchFn: WeatherFetch, name: string): Promise<WeatherPlace | null>;
+/**
+ * Fetches the conditions at a place.
+ *
+ * @param fetchFn - The fetch to go through.
+ * @param place - Where.
+ * @param units - Metric (°C, km/h) or imperial (°F, mph).
+ * @param days - How many days of forecast.
+ * @returns The report.
+ * @throws {Error} When the service cannot be reached or answers without the
+ *   fields a report is made of.
+ */
+export declare function report_fetch(fetchFn: WeatherFetch, place: WeatherPlace, units: WeatherUnits, days: number): Promise<WeatherReport>;
+/**
+ * Renders a report as the lines a terminal shows.
+ *
+ * @param report - The report.
+ * @returns The text, with a trailing newline.
+ */
+export declare function report_render(report: WeatherReport): string;
+/**
+ * Reports the weather at a place.
+ *
+ * @param args - `[place…] [-u|--units metric|imperial] [-d|--days N]`.
+ * @param fetchFn - The fetch to go through; the global one unless a test
+ *   hands in its own.
+ * @returns An envelope carrying the rendered report and the typed report
+ *   beneath it; an error envelope when a flag is unknown, the place is not
+ *   found, or the service cannot be reached.
+ */
+export declare function builtin_weather(args: string[], fetchFn?: WeatherFetch): Promise<CommandEnvelope>;
+export {};