@fnndsc/brasa 0.23.2 → 0.25.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/motd.d.ts

@@ -0,0 +1,41 @@
+/**
+ * @file Builtin motd.
+ *
+ * The message of the day: the greeting a session gives the operator who
+ * has just arrived. A kernel command, so a TTY and a browser say the same
+ * thing — who you are, how many feeds you hold, how many jobs have run
+ * and how many of them failed, what is running now — from the session's
+ * own index, which costs no call. While the index is still warming the
+ * greeting says what it holds so far and says so, rather than keeping the
+ * operator waiting for a number.
+ *
+ * A surface may say where the operator has arrived (`motd ARGUS`); the
+ * kernel does not know its surfaces by name and should not.
+ *
+ * @module
+ */
+import { CommandEnvelope } from '@fnndsc/cumin';
+import { type SessionMotd } from '@fnndsc/menu';
+/**
+ * Gathers the greeting's facts from the session's own index.
+ *
+ * @param user - Who arrived.
+ * @param surface - Where, as the surface said it; empty for none.
+ * @returns The facts.
+ */
+export declare function motd_gather(user: string, surface: string): SessionMotd;
+/**
+ * Renders the greeting.
+ *
+ * @param motd - The facts.
+ * @returns The text, with a trailing newline.
+ */
+export declare function motd_render(motd: SessionMotd): string;
+/**
+ * Greets the operator.
+ *
+ * @param args - Optionally where the operator arrived, e.g. `ARGUS` or
+ *   `chell`; the word goes into the greeting as given. No flags.
+ * @returns An envelope carrying the greeting and the `session.motd` model.
+ */
+export declare function builtin_motd(args: string[]): Promise<CommandEnvelope>;

package/dist/builtins/sys/motd.js

@@ -0,0 +1,139 @@
+/**
+ * @file Builtin motd.
+ *
+ * The message of the day: the greeting a session gives the operator who
+ * has just arrived. A kernel command, so a TTY and a browser say the same
+ * thing — who you are, how many feeds you hold, how many jobs have run
+ * and how many of them failed, what is running now — from the session's
+ * own index, which costs no call. While the index is still warming the
+ * greeting says what it holds so far and says so, rather than keeping the
+ * operator waiting for a number.
+ *
+ * A surface may say where the operator has arrived (`motd ARGUS`); the
+ * kernel does not know its surfaces by name and should not.
+ *
+ * @module
+ */
+import { envelope_ok, procCache_get } from '@fnndsc/cumin';
+import { context_getSingle } from '@fnndsc/salsa';
+import { SESSION_MOTD_MODEL_KIND } from '@fnndsc/menu';
+import { jobsState_derive } from '../../core/jobsState.js';
+import { fortune_random } from './fortune.js';
+/** The most lines a greeting's fortune may run to. */
+const FORTUNE_LINES_MAX = 4;
+/**
+ * Says a count the way a person reads one.
+ *
+ * @param n - The count.
+ * @returns The count with thousands separated.
+ */
+function count_say(n) {
+    return n.toLocaleString('en-US');
+}
+/**
+ * Says a failure rate as a percentage with one decimal, or as a whole
+ * number when it is one.
+ *
+ * @param rate - 0..1.
+ * @returns The percentage, e.g. `1.3 %`.
+ */
+function rate_say(rate) {
+    const percent = rate * 100;
+    const text = Number.isInteger(percent) ? String(percent) : percent.toFixed(1);
+    return `${text} %`;
+}
+/**
+ * Gathers the greeting's facts from the session's own index.
+ *
+ * @param user - Who arrived.
+ * @param surface - Where, as the surface said it; empty for none.
+ * @returns The facts.
+ */
+export function motd_gather(user, surface) {
+    const cache = procCache_get();
+    const feeds = cache.feeds_find('');
+    const scope = cache.feedScopeCounts_get(user);
+    const state = jobsState_derive(feeds);
+    let finished = 0;
+    let errored = 0;
+    let cancelled = 0;
+    let total = 0;
+    for (const feed of feeds) {
+        finished += feed.finishedJobs;
+        errored += feed.erroredJobs;
+        cancelled += feed.cancelledJobs;
+        total += feed.finishedJobs + feed.erroredJobs + feed.cancelledJobs + feed.startedJobs + feed.scheduledJobs + feed.createdJobs;
+    }
+    const settled = finished + errored;
+    const warmup = cache.warmupProgress_get();
+    const lifecycle = cache.lifecycle_get().state;
+    const index = {
+        state: lifecycle === 'current' ? 'current' : warmup.active || warmup.loaded > 0 ? 'warming' : 'cold',
+        loaded: warmup.loaded,
+        total: warmup.total,
+    };
+    return {
+        user,
+        surface,
+        feeds: { total: scope.total, own: scope.user, shared: scope.shared, public: scope.public },
+        jobs: { total, finished, errored, cancelled, running: state.running, scheduled: state.scheduled },
+        failureRate: settled > 0 ? errored / settled : null,
+        index,
+        fortune: fortune_random(FORTUNE_LINES_MAX),
+    };
+}
+/**
+ * Renders the greeting.
+ *
+ * @param motd - The facts.
+ * @returns The text, with a trailing newline.
+ */
+export function motd_render(motd) {
+    const where = motd.surface.length > 0 ? ` to ${motd.surface}` : '';
+    const lines = [`Welcome${where}, ${motd.user}.`];
+    const facts = [];
+    if (motd.index.state === 'cold' && motd.feeds.total === 0) {
+        facts.push('your index is still cold: the feeds and jobs arrive as it warms');
+    }
+    else {
+        facts.push(`${count_say(motd.feeds.total)} feed${motd.feeds.total === 1 ? '' : 's'}`);
+        const jobsWord = motd.index.state === 'current'
+            ? `${count_say(motd.jobs.total)} jobs run`
+            : motd.index.total > 0
+                ? `${count_say(motd.index.loaded)} of ${count_say(motd.index.total)} jobs indexed so far`
+                : `${count_say(motd.jobs.total)} jobs indexed so far`;
+        facts.push(jobsWord);
+        if (motd.failureRate !== null)
+            facts.push(`${rate_say(motd.failureRate)} failed`);
+        if (motd.jobs.running > 0 || motd.jobs.scheduled > 0) {
+            facts.push(`${count_say(motd.jobs.running)} running, ${count_say(motd.jobs.scheduled)} scheduled`);
+        }
+    }
+    lines.push(facts.join(' · '));
+    if (motd.fortune.length > 0) {
+        lines.push('');
+        lines.push(motd.fortune);
+    }
+    return `${lines.join('\n')}\n`;
+}
+/**
+ * Greets the operator.
+ *
+ * @param args - Optionally where the operator arrived, e.g. `ARGUS` or
+ *   `chell`; the word goes into the greeting as given. No flags.
+ * @returns An envelope carrying the greeting and the `session.motd` model.
+ */
+export async function builtin_motd(args) {
+    const flag = args.find((arg) => arg.startsWith('-'));
+    if (flag !== undefined) {
+        return envelope_ok(`motd: unknown option '${flag}' (usage: motd [surface])\n`);
+    }
+    const context = await context_getSingle();
+    const user = context.user ?? '';
+    if (user.length === 0) {
+        return envelope_ok('Welcome. You are not connected: connect --user <user> --password <pwd> <url>\n');
+    }
+    const motd = motd_gather(user, args.join(' '));
+    return envelope_ok(motd_render(motd), { kind: SESSION_MOTD_MODEL_KIND, data: motd });
+}
+//# sourceMappingURL=motd.js.map

package/dist/builtins/sys/motd.js.map

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