@fnndsc/brasa 0.23.2 → 0.24.0

package/dist/builtins/sys/weather.js

@@ -0,0 +1,297 @@
+/**
+ * @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 { envelope_error, envelope_ok } from '@fnndsc/cumin';
+/** Where `weather` looks when given no place. */
+export const WEATHER_DEFAULT_PLACE = 'Boston';
+/** Days of forecast shown when none are asked for. */
+const DAYS_DEFAULT = 3;
+/** The system used when none is asked for: the lab reports in metric. */
+export const WEATHER_UNITS_DEFAULT = 'metric';
+/** The most forecast days Open-Meteo answers. */
+const DAYS_MAX = 16;
+/** How long one call may take before the report gives up. */
+const FETCH_TIMEOUT_MS = 8_000;
+/** The geocoder: a name to coordinates. */
+const GEOCODE_URL = 'https://geocoding-api.open-meteo.com/v1/search';
+/** The forecast itself. */
+const FORECAST_URL = 'https://api.open-meteo.com/v1/forecast';
+/** The compass, eight points, clockwise from north. */
+const COMPASS = ['N', 'NE', 'E', 'SE', 'S', 'SW', 'W', 'NW'];
+/** WMO weather interpretation codes, as Open-Meteo reports them, in words. */
+const CONDITIONS = {
+    0: 'clear sky',
+    1: 'mainly clear',
+    2: 'partly cloudy',
+    3: 'overcast',
+    45: 'fog',
+    48: 'rime fog',
+    51: 'light drizzle',
+    53: 'drizzle',
+    55: 'dense drizzle',
+    56: 'light freezing drizzle',
+    57: 'freezing drizzle',
+    61: 'light rain',
+    63: 'rain',
+    65: 'heavy rain',
+    66: 'light freezing rain',
+    67: 'freezing rain',
+    71: 'light snow',
+    73: 'snow',
+    75: 'heavy snow',
+    77: 'snow grains',
+    80: 'light rain showers',
+    81: 'rain showers',
+    82: 'violent rain showers',
+    85: 'light snow showers',
+    86: 'heavy snow showers',
+    95: 'thunderstorm',
+    96: 'thunderstorm with light hail',
+    99: 'thunderstorm with heavy hail',
+};
+/**
+ * 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 function condition_ofCode(code) {
+    return CONDITIONS[code] ?? `conditions code ${code}`;
+}
+/**
+ * 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 function compass_ofDegrees(degrees) {
+    const index = Math.round((((degrees % 360) + 360) % 360) / 45) % 8;
+    return COMPASS[index];
+}
+/**
+ * Reads a number out of an untyped JSON field.
+ *
+ * @param value - The field.
+ * @returns The number, or null when the field is not one.
+ */
+function number_read(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : null;
+}
+/**
+ * Reads a string out of an untyped JSON field.
+ *
+ * @param value - The field.
+ * @returns The string, or the empty string when the field is not one.
+ */
+function string_read(value) {
+    return typeof value === 'string' ? value : '';
+}
+/**
+ * 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 function weatherArgs_parse(args) {
+    const words = [];
+    let units = WEATHER_UNITS_DEFAULT;
+    let days = DAYS_DEFAULT;
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === '-u' || arg === '--units' || arg.startsWith('--units=')) {
+            const value = arg.startsWith('--units=') ? arg.slice('--units='.length) : (args[++i] ?? '');
+            if (value !== 'metric' && value !== 'imperial') {
+                return `weather: --units takes metric or imperial, not '${value}'`;
+            }
+            units = value;
+        }
+        else if (arg === '-d' || arg === '--days') {
+            const value = parseInt(args[i + 1] ?? '', 10);
+            if (!Number.isFinite(value) || value < 1 || value > DAYS_MAX) {
+                return `weather: ${arg} takes a number of days, 1 to ${DAYS_MAX}`;
+            }
+            days = value;
+            i++;
+        }
+        else if (arg.startsWith('-')) {
+            return `weather: unknown option '${arg}' (usage: weather [place] [-u|--units metric|imperial] [-d|--days N])`;
+        }
+        else {
+            words.push(arg);
+        }
+    }
+    return { place: words.length > 0 ? words.join(' ') : WEATHER_DEFAULT_PLACE, units, days };
+}
+/**
+ * Fetches one JSON answer, bounded in time.
+ *
+ * @param fetchFn - The fetch to go through.
+ * @param url - What to ask.
+ * @returns The parsed body.
+ * @throws {Error} When the service is unreachable, answers an error, or
+ *   answers something that is not JSON.
+ */
+async function json_fetch(fetchFn, url) {
+    const response = await fetchFn(url, { signal: AbortSignal.timeout(FETCH_TIMEOUT_MS) });
+    if (!response.ok)
+        throw new Error(`open-meteo answered ${response.status}`);
+    return response.json();
+}
+/**
+ * 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 async function place_find(fetchFn, name) {
+    const url = `${GEOCODE_URL}?name=${encodeURIComponent(name)}&count=1&language=en&format=json`;
+    const answer = (await json_fetch(fetchFn, url));
+    const first = answer.results?.[0];
+    const latitude = number_read(first?.latitude);
+    const longitude = number_read(first?.longitude);
+    if (first === undefined || latitude === null || longitude === null)
+        return null;
+    return {
+        name: string_read(first.name),
+        region: string_read(first.admin1),
+        country: string_read(first.country),
+        latitude,
+        longitude,
+        timezone: string_read(first.timezone) || 'auto',
+    };
+}
+/**
+ * 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 async function report_fetch(fetchFn, place, units, days) {
+    const celsius = units === 'metric';
+    const query = [
+        `latitude=${place.latitude}`,
+        `longitude=${place.longitude}`,
+        'current=temperature_2m,apparent_temperature,relative_humidity_2m,weather_code,wind_speed_10m,wind_direction_10m',
+        'daily=weather_code,temperature_2m_max,temperature_2m_min',
+        `temperature_unit=${celsius ? 'celsius' : 'fahrenheit'}`,
+        `wind_speed_unit=${celsius ? 'kmh' : 'mph'}`,
+        `timezone=${encodeURIComponent(place.timezone)}`,
+        `forecast_days=${days}`,
+    ].join('&');
+    const answer = (await json_fetch(fetchFn, `${FORECAST_URL}?${query}`));
+    const current = answer.current;
+    const temperature = number_read(current?.temperature_2m);
+    const code = number_read(current?.weather_code);
+    if (current === undefined || temperature === null || code === null) {
+        throw new Error('open-meteo answered without current conditions');
+    }
+    const now = {
+        time: string_read(current.time),
+        temperature,
+        apparent: number_read(current.apparent_temperature) ?? temperature,
+        humidity: number_read(current.relative_humidity_2m) ?? 0,
+        code,
+        condition: condition_ofCode(code),
+        windSpeed: number_read(current.wind_speed_10m) ?? 0,
+        windDirection: compass_ofDegrees(number_read(current.wind_direction_10m) ?? 0),
+    };
+    const dates = Array.isArray(answer.daily?.time) ? answer.daily.time : [];
+    const highs = Array.isArray(answer.daily?.temperature_2m_max) ? answer.daily.temperature_2m_max : [];
+    const lows = Array.isArray(answer.daily?.temperature_2m_min) ? answer.daily.temperature_2m_min : [];
+    const codes = Array.isArray(answer.daily?.weather_code) ? answer.daily.weather_code : [];
+    const forecast = [];
+    for (let i = 0; i < dates.length; i++) {
+        const high = number_read(highs[i]);
+        const low = number_read(lows[i]);
+        const dayCode = number_read(codes[i]);
+        if (high === null || low === null || dayCode === null)
+            continue;
+        forecast.push({ date: string_read(dates[i]), low, high, code: dayCode, condition: condition_ofCode(dayCode) });
+    }
+    return { place, units: celsius ? 'C' : 'F', now, days: forecast };
+}
+/**
+ * Names a forecast day: `today`, then the weekday and date.
+ *
+ * @param date - The day as `YYYY-MM-DD`.
+ * @param index - Its position in the forecast, 0 being today.
+ * @returns The label.
+ */
+function day_label(date, index) {
+    if (index === 0)
+        return 'today';
+    const parsed = new Date(`${date}T12:00:00Z`);
+    const weekday = ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'][parsed.getUTCDay()] ?? '';
+    return `${weekday} ${date.slice(5)}`;
+}
+/**
+ * Renders a report as the lines a terminal shows.
+ *
+ * @param report - The report.
+ * @returns The text, with a trailing newline.
+ */
+export function report_render(report) {
+    const unit = `°${report.units}`;
+    const speed = report.units === 'C' ? 'km/h' : 'mph';
+    const where = [report.place.name, report.place.region, report.place.country]
+        .filter((part) => part.length > 0)
+        .join(', ');
+    const when = report.now.time.replace('T', ' ');
+    const lines = [
+        `${where} · ${when}`,
+        `  now       ${Math.round(report.now.temperature)}${unit} (feels ${Math.round(report.now.apparent)}${unit}) · ${report.now.condition} · wind ${Math.round(report.now.windSpeed)} ${speed} ${report.now.windDirection} · humidity ${Math.round(report.now.humidity)}%`,
+    ];
+    report.days.forEach((day, index) => {
+        lines.push(`  ${day_label(day.date, index).padEnd(9)} ${Math.round(day.low)}–${Math.round(day.high)}${unit} · ${day.condition}`);
+    });
+    return `${lines.join('\n')}\n`;
+}
+/**
+ * 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 async function builtin_weather(args, fetchFn = (url, init) => fetch(url, init)) {
+    const parsed = weatherArgs_parse(args);
+    if (typeof parsed === 'string')
+        return envelope_error(`${parsed}\n`);
+    try {
+        const place = await place_find(fetchFn, parsed.place);
+        if (place === null)
+            return envelope_error(`weather: no such place '${parsed.place}'\n`);
+        const report = await report_fetch(fetchFn, place, parsed.units, parsed.days);
+        return envelope_ok(report_render(report), { kind: 'sys.weather', data: report });
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        return envelope_error(`weather: ${reason}\n`);
+    }
+}
+//# sourceMappingURL=weather.js.map

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

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

package/dist/command-keys.js

@@ -21,6 +21,10 @@ export const COMMAND_HANDLERS_KEYS = [
     'files', 'links', 'dirs',
     'store',
     'tag', 'tags',
+    'expect',
+    'play',
+    'record',
+    'gather',
     'group', 'groups',
     'user', 'users',
     'pluginmeta', 'pluginmetas', 'meta', 'metas',

package/dist/command-keys.js.map

@@ -1 +1 @@
-{"version":3,"file":"command-keys.js","sourceRoot":"","sources":["../src/command-keys.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,CAAC,MAAM,qBAAqB,GAAa;IAC7C,aAAa;IACb,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI;IAC1E,QAAQ,EAAE,UAAU,EAAE,MAAM;IAC5B,MAAM;IACN,SAAS,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU;IAChD,MAAM;IACN,SAAS,EAAE,cAAc,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE,QAAQ,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM;IAClG,kCAAkC;IAClC,QAAQ,EAAE,SAAS;IACnB,MAAM,EAAE,OAAO;IACf,UAAU,EAAE,WAAW;IACvB,SAAS,EAAE,UAAU;IACrB,OAAO,EAAE,OAAO,EAAE,MAAM;IACxB,OAAO;IACP,KAAK,EAAE,MAAM;IACb,OAAO,EAAE,QAAQ;IACjB,MAAM,EAAE,OAAO;IACf,YAAY,EAAE,aAAa,EAAE,MAAM,EAAE,OAAO;IAC5C,gBAAgB,EAAE,iBAAiB,EAAE,UAAU,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM;IAC3E,UAAU,EAAE,WAAW;IACvB,oBAAoB;IACpB,kBAAkB;IAClB,aAAa,EAAE,aAAa,EAAE,cAAc;CAC7C,CAAC"}
+{"version":3,"file":"command-keys.js","sourceRoot":"","sources":["../src/command-keys.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,CAAC,MAAM,qBAAqB,GAAa;IAC7C,aAAa;IACb,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI;IAC1E,QAAQ,EAAE,UAAU,EAAE,MAAM;IAC5B,MAAM;IACN,SAAS,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU;IAChD,MAAM;IACN,SAAS,EAAE,cAAc,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE,QAAQ,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM;IAClG,kCAAkC;IAClC,QAAQ,EAAE,SAAS;IACnB,MAAM,EAAE,OAAO;IACf,UAAU,EAAE,WAAW;IACvB,SAAS,EAAE,UAAU;IACrB,OAAO,EAAE,OAAO,EAAE,MAAM;IACxB,OAAO;IACP,KAAK,EAAE,MAAM;IACb,QAAQ;IACR,MAAM;IACN,QAAQ;IACR,QAAQ;IACR,OAAO,EAAE,QAAQ;IACjB,MAAM,EAAE,OAAO;IACf,YAAY,EAAE,aAAa,EAAE,MAAM,EAAE,OAAO;IAC5C,gBAAgB,EAAE,iBAAiB,EAAE,UAAU,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM;IAC3E,UAAU,EAAE,WAAW;IACvB,oBAAoB;IACpB,kBAAkB;IAClB,aAAa,EAAE,aAAa,EAAE,cAAc;CAC7C,CAAC"}

package/dist/core/connect.d.ts

@@ -5,7 +5,8 @@
  * context and validate its token against the server. It carries no terminal
  * output of its own: it returns a status a frontend narrates (the CLI prints
  * progress; a daemon logs or exits). Interactive login (prompting for a URL and
- * password) is a frontend concern and lives with the CLI, not here.
+ * password) is a frontend concern and lives with the CLI, not here. A token a
+ * door already minted is the other headless way in, and it is here too.
  *
  * @module
  */
@@ -36,3 +37,32 @@ export interface SavedSessionResult {
  * @returns The restore outcome and the resolved context.
  */
 export declare function sessionConnect_fromSaved(): Promise<SavedSessionResult>;
+/**
+ * The outcome of a token hand-over.
+ *
+ * - `connected` — the server accepted the token; the session is this identity's.
+ * - `refused` — the server did not; the session is offline and `error` says why.
+ */
+export interface TokenSessionResult {
+    status: 'connected' | 'refused';
+    context: SingleContext;
+    /** What the server said, when the status is `refused`. */
+    error?: string;
+}
+/**
+ * Connects a session from a CUBE token a door already minted, without prompting.
+ *
+ * A login front on a shared host exchanges the operator's password for a
+ * token itself and hands the token to the session it spawns; the session
+ * never sees a password. The token is proved against the server before the
+ * context is written, so a refusal changes nothing on disk. On acceptance
+ * the context is set the way a credentialed boot sets it: the identity, and
+ * no feed or plugin — the working directory is the identity's own and is
+ * not touched, so a session that was evicted comes back where it was.
+ *
+ * @param user - The CUBE username the token was minted for.
+ * @param url - The CUBE API base the token was minted against.
+ * @param token - The token.
+ * @returns Connected, or refused with the server's reason.
+ */
+export declare function sessionConnect_withToken(user: string, url: string, token: string): Promise<TokenSessionResult>;

package/dist/core/connect.js

@@ -5,12 +5,14 @@
  * context and validate its token against the server. It carries no terminal
  * output of its own: it returns a status a frontend narrates (the CLI prints
  * progress; a daemon logs or exits). Interactive login (prompting for a URL and
- * password) is a frontend concern and lives with the CLI, not here.
+ * password) is a frontend concern and lives with the CLI, not here. A token a
+ * door already minted is the other headless way in, and it is here too.
  *
  * @module
  */
 import { session } from '../session/index.js';
 import { context_getSingle } from '@fnndsc/salsa';
+import { chrisContext, Context } from '@fnndsc/cumin';
 /**
  * Restores a session from saved credentials, without any prompting.
  *
@@ -43,4 +45,33 @@ export async function sessionConnect_fromSaved() {
         return { status: 'invalid-token', context, error: error instanceof Error ? error.message : String(error) };
     }
 }
+/**
+ * Connects a session from a CUBE token a door already minted, without prompting.
+ *
+ * A login front on a shared host exchanges the operator's password for a
+ * token itself and hands the token to the session it spawns; the session
+ * never sees a password. The token is proved against the server before the
+ * context is written, so a refusal changes nothing on disk. On acceptance
+ * the context is set the way a credentialed boot sets it: the identity, and
+ * no feed or plugin — the working directory is the identity's own and is
+ * not touched, so a session that was evicted comes back where it was.
+ *
+ * @param user - The CUBE username the token was minted for.
+ * @param url - The CUBE API base the token was minted against.
+ * @param token - The token.
+ * @returns Connected, or refused with the server's reason.
+ */
+export async function sessionConnect_withToken(user, url, token) {
+    const outcome = await session.connection.connection_connectWithToken({ user, url, token });
+    if (!outcome.connected) {
+        session.offline = true;
+        return { status: 'refused', context: await context_getSingle(), error: outcome.reason };
+    }
+    session.offline = false;
+    await chrisContext.current_set(Context.ChRISuser, user);
+    await chrisContext.current_set(Context.ChRISURL, url);
+    await chrisContext.current_set(Context.ChRISfeed, '');
+    await chrisContext.current_set(Context.ChRISplugin, '');
+    return { status: 'connected', context: await context_getSingle() };
+}
 //# sourceMappingURL=connect.js.map

package/dist/core/connect.js.map

@@ -1 +1 @@
-{"version":3,"file":"connect.js","sourceRoot":"","sources":["../../src/core/connect.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAC9C,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAsBlD;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,wBAAwB;IAC5C,MAAM,OAAO,GAAkB,MAAM,iBAAiB,EAAE,CAAC;IAEzD,IAAI,CAAC,OAAO,CAAC,IAAI,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC;QAClC,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,OAAO,EAAE,CAAC;IAC3C,CAAC;IAED,MAAM,KAAK,GAAkB,MAAM,OAAO,CAAC,UAAU,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC;IAC1E,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC;QACvB,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,OAAO,EAAE,CAAC;IACzC,CAAC;IAED,IAAI,CAAC;QACH,MAAM,MAAM,GAAkB,MAAM,OAAO,CAAC,UAAU,CAAC,UAAU,EAAE,CAAC;QACpE,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC;YACvB,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,OAAO,EAAE,CAAC;QAC1C,CAAC;QACD,MAAM,MAAM,CAAC,OAAO,EAAE,CAAC;QACvB,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,OAAO,EAAE,CAAC;IACzC,CAAC;IAAC,OAAO,KAAc,EAAE,CAAC;QACxB,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC;QACvB,OAAO,EAAE,MAAM,EAAE,eAAe,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;IAC7G,CAAC;AACH,CAAC"}
+{"version":3,"file":"connect.js","sourceRoot":"","sources":["../../src/core/connect.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAC9C,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAClD,OAAO,EAAyB,YAAY,EAAE,OAAO,EAA4B,MAAM,eAAe,CAAC;AAqBvG;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,wBAAwB;IAC5C,MAAM,OAAO,GAAkB,MAAM,iBAAiB,EAAE,CAAC;IAEzD,IAAI,CAAC,OAAO,CAAC,IAAI,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC;QAClC,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,OAAO,EAAE,CAAC;IAC3C,CAAC;IAED,MAAM,KAAK,GAAkB,MAAM,OAAO,CAAC,UAAU,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC;IAC1E,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC;QACvB,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,OAAO,EAAE,CAAC;IACzC,CAAC;IAED,IAAI,CAAC;QACH,MAAM,MAAM,GAAkB,MAAM,OAAO,CAAC,UAAU,CAAC,UAAU,EAAE,CAAC;QACpE,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC;YACvB,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,OAAO,EAAE,CAAC;QAC1C,CAAC;QACD,MAAM,MAAM,CAAC,OAAO,EAAE,CAAC;QACvB,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,OAAO,EAAE,CAAC;IACzC,CAAC;IAAC,OAAO,KAAc,EAAE,CAAC;QACxB,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC;QACvB,OAAO,EAAE,MAAM,EAAE,eAAe,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;IAC7G,CAAC;AACH,CAAC;AAeD;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,KAAK,UAAU,wBAAwB,CAAC,IAAY,EAAE,GAAW,EAAE,KAAa;IACrF,MAAM,OAAO,GAAwB,MAAM,OAAO,CAAC,UAAU,CAAC,2BAA2B,CAAC,EAAE,IAAI,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC,CAAC;IAChH,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,CAAC;QACvB,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC;QACvB,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,iBAAiB,EAAE,EAAE,KAAK,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC;IAC1F,CAAC;IACD,OAAO,CAAC,OAAO,GAAG,KAAK,CAAC;IACxB,MAAM,YAAY,CAAC,WAAW,CAAC,OAAO,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;IACxD,MAAM,YAAY,CAAC,WAAW,CAAC,OAAO,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;IACtD,MAAM,YAAY,CAAC,WAAW,CAAC,OAAO,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC;IACtD,MAAM,YAAY,CAAC,WAAW,CAAC,OAAO,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC;IACxD,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,iBAAiB,EAAE,EAAE,CAAC;AACrE,CAAC"}

package/dist/core/dispatch.d.ts

@@ -25,20 +25,6 @@ export { COMMAND_HANDLERS_KEYS } from '../command-keys.js';
  * @param enabled - Whether timing display is active.
  */
 export declare function command_timingMaybePrint(startTime: number, enabled: boolean): void;
-/**
- * Expands `$NAME` and `${NAME}` environment references in one token.
- *
- * Applied per token after parsing, so an expanded value can never inject
- * command separators, pipes or redirects (the structural characters were
- * already consumed). References to unset variables are left verbatim —
- * kinder than the shell's silent empty string when a script forgets an
- * export. Shell-escape lines (`!...`) never reach this point; bash does
- * its own expansion there.
- *
- * @param token - A single parsed command token.
- * @returns The token with set environment references substituted.
- */
-export declare function envRefs_expand(token: string): string;
 /**
  * Dispatches a parsed command to its handler and returns its envelope, with
  * any errors the command left on the stack drained into the envelope.

package/dist/core/dispatch.js

@@ -14,16 +14,18 @@
  */
 import { writeFileSync, appendFileSync } from 'fs';
 import chalk from 'chalk';
-import { builtin_cd, builtin_ls, builtin_pwd, builtin_connect, builtin_logout, builtin_cat, builtin_cp, builtin_mv, builtin_upload, builtin_pacs, builtin_pipeline, builtin_pull, builtin_query, builtin_cubepath, builtin_dcm, builtin_image, builtin_rm, builtin_setfacl, builtin_getfacl, builtin_touch, builtin_mkdir, builtin_plugin, builtin_feed, builtin_compute, builtin_tag, builtin_group, builtin_user, builtin_pluginmeta, builtin_plugininstance, builtin_workflow, builtin_download, builtin_edit, builtin_config, builtin_files, builtin_links, builtin_dirs, builtin_context, builtin_parametersofplugin, builtin_physicalmode, builtin_timing, builtin_id, builtin_whoami, builtin_whereami, builtin_version, builtin_fortune, builtin_date, builtin_cal, builtin_debug, builtin_help, builtin_tree, builtin_du, builtin_store, error_stripDebugPrefix } from '../builtins/index.js';
+import { builtin_cd, builtin_ls, builtin_pwd, builtin_connect, builtin_logout, builtin_cat, builtin_cp, builtin_mv, builtin_upload, builtin_pacs, builtin_pipeline, builtin_pull, builtin_query, builtin_cubepath, builtin_dcm, builtin_image, builtin_rm, builtin_setfacl, builtin_getfacl, builtin_touch, builtin_mkdir, builtin_plugin, builtin_feed, builtin_compute, builtin_tag, builtin_expect, builtin_play, builtin_record, builtin_gather, builtin_group, builtin_user, builtin_pluginmeta, builtin_plugininstance, builtin_workflow, builtin_download, builtin_edit, builtin_config, builtin_files, builtin_links, builtin_dirs, builtin_context, builtin_parametersofplugin, builtin_physicalmode, builtin_timing, builtin_id, builtin_whoami, builtin_whereami, builtin_version, builtin_fortune, builtin_weather, builtin_date, builtin_cal, builtin_debug, builtin_help, builtin_tree, builtin_du, builtin_store, error_stripDebugPrefix } from '../builtins/index.js';
 import { builtin_executePlugin } from '../builtins/pluginExecute.js';
 import { builtin_proc } from '../builtins/proc.js';
 import { shellWords_expand } from '../builtins/wildcard.js';
 import { help_render, commandHelp_get, pipelineExecutableHelp_render, args_checkHasHelpFlag, } from '../builtins/help.js';
 import { pluginExecutable_handle } from '../builtins/executable.js';
-import { errorStack, Ok, envelope_error } from '@fnndsc/cumin';
+import { errorStack, Ok, Err, envelope_error } from '@fnndsc/cumin';
 import { envelopeHandler_wrap, envelope_deliver, sink_get, PipeCaptureSink, sinkScope_run } from './sink.js';
+import { reference_refusal, reference_resolve, unresolvedStands_get, verbInHand_set } from './expansion.js';
+import { answer_note, answerConsulted_take } from '../session/answer.js';
 import { vfs } from '../lib/vfs/vfs.js';
-import { shellArguments_envRefsExpand, shellWords_tokenize, shellWords_values, } from '../lib/parser.js';
+import { shellWords_referencesExpand, shellWords_tokenize, shellWords_values, } from '../lib/parser.js';
 import { surface_get, capability_require } from './surface.js';
 import { sudoCommand_run } from './elevation.js';
 import { redirectTarget_resolve, pathnameExpansion_isEligible, } from './preprocess.js';
@@ -76,6 +78,7 @@ export const ENVELOPE_HANDLERS = {
     debug: builtin_debug,
     version: builtin_version,
     fortune: builtin_fortune,
+    weather: builtin_weather,
     date: builtin_date,
     cal: builtin_cal,
     ls: builtin_ls,
@@ -94,6 +97,10 @@ export const ENVELOPE_HANDLERS = {
     computes: builtin_compute,
     tag: builtin_tag,
     tags: builtin_tag,
+    expect: builtin_expect,
+    play: builtin_play,
+    record: builtin_record,
+    gather: builtin_gather,
     group: builtin_group,
     groups: builtin_group,
     user: builtin_user,
@@ -166,6 +173,7 @@ export const COMMAND_HANDLERS = {
     whereami: envelopeHandler_wrap(builtin_whereami),
     debug: envelopeHandler_wrap(builtin_debug),
     fortune: envelopeHandler_wrap(builtin_fortune),
+    weather: envelopeHandler_wrap(builtin_weather),
     date: envelopeHandler_wrap(builtin_date),
     cal: envelopeHandler_wrap(builtin_cal),
     help: envelopeHandler_wrap(builtin_help),
@@ -181,6 +189,10 @@ export const COMMAND_HANDLERS = {
     computes: envelopeHandler_wrap(builtin_compute),
     tag: envelopeHandler_wrap(builtin_tag),
     tags: envelopeHandler_wrap(builtin_tag),
+    expect: envelopeHandler_wrap(builtin_expect),
+    play: envelopeHandler_wrap(builtin_play),
+    record: envelopeHandler_wrap(builtin_record),
+    gather: envelopeHandler_wrap(builtin_gather),
     group: envelopeHandler_wrap(builtin_group),
     groups: envelopeHandler_wrap(builtin_group),
     pluginmeta: envelopeHandler_wrap(builtin_pluginmeta),
@@ -277,25 +289,6 @@ async function binExecutableMatches_get(command) {
         pipeline: binResult.value.find((item) => item.name === command && item.type === 'pipeline'),
     };
 }
-/**
- * Expands `$NAME` and `${NAME}` environment references in one token.
- *
- * Applied per token after parsing, so an expanded value can never inject
- * command separators, pipes or redirects (the structural characters were
- * already consumed). References to unset variables are left verbatim —
- * kinder than the shell's silent empty string when a script forgets an
- * export. Shell-escape lines (`!...`) never reach this point; bash does
- * its own expansion there.
- *
- * @param token - A single parsed command token.
- * @returns The token with set environment references substituted.
- */
-export function envRefs_expand(token) {
-    return token.replace(/\$(?:\{([A-Za-z_][A-Za-z0-9_]*)\}|([A-Za-z_][A-Za-z0-9_]*))/g, (match, braced, bare) => {
-        const value = process.env[braced ?? bare ?? ''];
-        return value !== undefined ? value : match;
-    });
-}
 /**
  * Reads the current process exit code as a number.
  *
@@ -386,7 +379,6 @@ async function commandDispatchEnvelope_run(command, args) {
     if (command === 'exit') {
         process.exit(0);
     }
-    args = shellArguments_envRefsExpand(args, envRefs_expand);
     if (command === 'sudo') {
         return await sudoCommand_run(args, commandDispatchEnvelope_run);
     }
@@ -490,6 +482,34 @@ async function helpEnvelope_maybe(command, args) {
  * @param args - Parsed argument words.
  * @returns Expanded compatibility arguments with expansion provenance.
  */
+/**
+ * Resolves the references in a whole command line, the command word included.
+ *
+ * A shell runs `$CMD arg`, and a manifest names its plugin as a parameter
+ * (`@param ANON = pl-pfdicom_tagSub-v3.3.4`) for exactly that reason: the
+ * same workflow on another CUBE supplies its own build. Expanding only the
+ * arguments left the command word as written, and the line refused with
+ * "command not found: ${ANON}".
+ *
+ * @param words - The line's tokenized words.
+ * @returns The words with references resolved, or a refusal naming the one
+ *   nothing could answer.
+ */
+async function commandLine_referencesExpand(words) {
+    // The verb is known before its operands expand, so an index can be
+    // refused by KIND: IMAGE given a study says so, instead of resolving to
+    // a path and failing later for a reason that names nothing typed. A
+    // `sudo` line's verb is the one after it.
+    const verb = words[0]?.value === 'sudo' ? words[1]?.value : words[0]?.value;
+    verbInHand_set(verb ?? null);
+    const expanded = await shellWords_referencesExpand(words, reference_resolve, unresolvedStands_get());
+    verbInHand_set(null);
+    if (!expanded.ok) {
+        errorStack.stack_push('error', reference_refusal(expanded.missing));
+        return Err();
+    }
+    return Ok(expanded.words);
+}
 async function commandWords_expand(command, args) {
     const sudoNestedCommand = command === 'sudo' ? args[0] : undefined;
     const targetCommand = sudoNestedCommand?.value ?? command;
@@ -515,10 +535,19 @@ async function chellCommand_executeAndCapture(commandLine) {
     const trimmedLine = commandLine.trim();
     if (!trimmedLine)
         return { text: '', buffer: Buffer.alloc(0) };
-    const words = shellWords_tokenize(trimmedLine);
-    if (words.length === 0) {
+    const tokenized = shellWords_tokenize(trimmedLine);
+    if (tokenized.length === 0) {
         return { text: '', buffer: Buffer.alloc(0) };
     }
+    const referenced = await commandLine_referencesExpand(tokenized);
+    if (!referenced.ok) {
+        const lastError = errorStack.stack_pop();
+        const message = lastError === undefined
+            ? 'unresolved reference'
+            : error_stripDebugPrefix(lastError.message);
+        return { text: chalk.red(`${message}\n`), buffer: Buffer.from('') };
+    }
+    const words = referenced.value;
     const [commandWord, ...argumentWords] = words;
     const command = commandWord.value;
     const expandResult = await commandWords_expand(command, argumentWords);
@@ -615,9 +644,26 @@ export async function pipe_execute(segments) {
  * @returns The command's envelope, or null when the line held no tokens.
  */
 export async function command_executeToEnvelope(trimmedLine, startTime, timingEnabled) {
-    const words = shellWords_tokenize(trimmedLine);
-    if (words.length === 0)
+    const tokenized = shellWords_tokenize(trimmedLine);
+    if (tokenized.length === 0)
         return null;
+    const referenced = await commandLine_referencesExpand(tokenized);
+    if (!referenced.ok) {
+        const lastError = errorStack.stack_pop();
+        // The refusal is the operator's to read, not the stack's: the debug
+        // prefix names the function that pushed it, which tells them nothing.
+        if (lastError)
+            sink_get().err_write(`${chalk.red(error_stripDebugPrefix(lastError.message))}\n`);
+        process.exitCode = 1;
+        return { status: 'error', rendered: '' };
+    }
+    const words = referenced.value;
+    // A line that acted on a number says which listing it counted: the rule
+    // that a readout which acts says so, applied to the rows it acted on.
+    const counted = answerConsulted_take();
+    if (counted !== null) {
+        sink_get().data_write(chalk.gray(`  from: ${counted.source} · ${counted.rows.length} rows\n`));
+    }
     const [commandWord, ...argumentWords] = words;
     const command = commandWord.value;
     const expandResult = await commandWords_expand(command, argumentWords);
@@ -647,10 +693,20 @@ export async function command_executeToEnvelope(trimmedLine, startTime, timingEn
         const result = failed
             ? { ...pluginEnvelope, status: 'error' }
             : pluginEnvelope;
+        if (result.model !== undefined) {
+            answer_note(result.model.kind, result.model.data, trimmedLine);
+        }
         return envelope_drainErrorsInto(checkpoint, result);
     }
     const envelope = await command_dispatchEnvelope(command, args);
     command_timingMaybePrint(startTime, timingEnabled);
+    // An answer with rows becomes the thing `@3` counts. Recorded from the
+    // MODEL, not from the rendering, so a console table and a graphical pane
+    // number the same rows — an index that meant different things on
+    // different surfaces would be worse than no index at all.
+    if (envelope.model !== undefined) {
+        answer_note(envelope.model.kind, envelope.model.data, trimmedLine);
+    }
     return envelope;
 }
 //# sourceMappingURL=dispatch.js.map