@fnndsc/brasa 0.34.0 → 0.35.0

package/dist/core/answerKinds.d.ts

@@ -0,0 +1,32 @@
+/**
+ * @file The kinds of row an index can name, and the kinds each verb takes.
+ *
+ * The core numbers files and folders; a backend adds the kinds its own
+ * listings carry (ChRIS: patients, studies, series) and says which of them its
+ * verbs take. Both are read when an index is resolved, so they follow the
+ * installed backend.
+ *
+ * @module
+ */
+import { type AnswerKindLook } from './backend.js';
+/**
+ * Every kind an index may name: the backend's first, then the core's.
+ *
+ * @returns The kinds, in that order.
+ */
+export declare function answerKinds_get(): ReadonlyArray<AnswerKindLook>;
+/**
+ * One kind, by its code.
+ *
+ * @param code - The three letters.
+ * @returns The kind, or undefined when nothing numbers it.
+ */
+export declare function answerKind_find(code: string): AnswerKindLook | undefined;
+/**
+ * What a verb can be handed by index: the core's kinds for it, then the
+ * backend's.
+ *
+ * @param verb - The command word.
+ * @returns The kinds, or undefined when the verb takes any kind.
+ */
+export declare function verbTakes_get(verb: string): ReadonlyArray<string> | undefined;

package/dist/core/answerKinds.js

@@ -0,0 +1,56 @@
+/**
+ * @file The kinds of row an index can name, and the kinds each verb takes.
+ *
+ * The core numbers files and folders; a backend adds the kinds its own
+ * listings carry (ChRIS: patients, studies, series) and says which of them its
+ * verbs take. Both are read when an index is resolved, so they follow the
+ * installed backend.
+ *
+ * @module
+ */
+import { backendInstalled_get } from './backend.js';
+/** The kinds the core numbers. */
+const CORE_KINDS = [
+    { code: 'FIL', word: 'a file', example: '@FIL2' },
+    { code: 'DIR', word: 'a folder', example: '@DIR4' },
+];
+/** What the core's own verbs take by index. */
+const CORE_TAKES = new Map([
+    ['cat', ['FIL']],
+    ['cd', ['DIR']],
+]);
+/**
+ * Every kind an index may name: the backend's first, then the core's.
+ *
+ * @returns The kinds, in that order.
+ */
+export function answerKinds_get() {
+    const backend = backendInstalled_get();
+    return [...(backend?.answerKinds ?? []), ...CORE_KINDS];
+}
+/**
+ * One kind, by its code.
+ *
+ * @param code - The three letters.
+ * @returns The kind, or undefined when nothing numbers it.
+ */
+export function answerKind_find(code) {
+    return answerKinds_get().find((kind) => kind.code === code);
+}
+/**
+ * What a verb can be handed by index: the core's kinds for it, then the
+ * backend's.
+ *
+ * @param verb - The command word.
+ * @returns The kinds, or undefined when the verb takes any kind.
+ */
+export function verbTakes_get(verb) {
+    const added = (backendInstalled_get()?.verbTakes ?? [])
+        .filter((entry) => entry.verb === verb)
+        .flatMap((entry) => entry.kinds);
+    const core = CORE_TAKES.get(verb);
+    if (core === undefined && added.length === 0)
+        return undefined;
+    return [...(core ?? []), ...added];
+}
+//# sourceMappingURL=answerKinds.js.map

package/dist/core/answerKinds.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"answerKinds.js","sourceRoot":"","sources":["../../src/core/answerKinds.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAE,oBAAoB,EAAqC,MAAM,cAAc,CAAC;AAEvF,kCAAkC;AAClC,MAAM,UAAU,GAAkC;IAChD,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,OAAO,EAAE;IACjD,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,UAAU,EAAE,OAAO,EAAE,OAAO,EAAE;CACpD,CAAC;AAEF,+CAA+C;AAC/C,MAAM,UAAU,GAA+C,IAAI,GAAG,CAAC;IACrE,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,CAAC;IAChB,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC;CAChB,CAAC,CAAC;AAEH;;;;GAIG;AACH,MAAM,UAAU,eAAe;IAC7B,MAAM,OAAO,GAAmB,oBAAoB,EAAE,CAAC;IACvD,OAAO,CAAC,GAAG,CAAC,OAAO,EAAE,WAAW,IAAI,EAAE,CAAC,EAAE,GAAG,UAAU,CAAC,CAAC;AAC1D,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAAC,IAAY;IAC1C,OAAO,eAAe,EAAE,CAAC,IAAI,CAAC,CAAC,IAAoB,EAAW,EAAE,CAAC,IAAI,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC;AACvF,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,aAAa,CAAC,IAAY;IACxC,MAAM,KAAK,GAAa,CAAC,oBAAoB,EAAE,EAAE,SAAS,IAAI,EAAE,CAAC;SAC9D,MAAM,CAAC,CAAC,KAAK,EAAW,EAAE,CAAC,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC;SAC/C,OAAO,CAAC,CAAC,KAAK,EAAyB,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IAC1D,MAAM,IAAI,GAAsC,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACrE,IAAI,IAAI,KAAK,SAAS,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,SAAS,CAAC;IAC/D,OAAO,CAAC,GAAG,CAAC,IAAI,IAAI,EAAE,CAAC,EAAE,GAAG,KAAK,CAAC,CAAC;AACrC,CAAC"}

package/dist/core/backend.d.ts

@@ -0,0 +1,261 @@
+/**
+ * @file The backend descriptor: everything a session needs that the core does
+ * not know.
+ *
+ * The engine runs over exactly one backend (docs/backend-neutral.adoc). The
+ * core asks it to prepare its own state, where the session's home is, and
+ * where the working directory was left, what the prompt shows and what the
+ * daemon heartbeats, which `${name}` references it answers and what kinds of
+ * row its listings number. ChRIS is one backend
+ * (`chris/backend.ts`), installed by the package entry; a host may install
+ * another before the engine boots.
+ *
+ * @module
+ */
+import type { PromptContext, CubeTelemetry, JobsStateTelemetry, CommandEnvelope, WatchState, Task } from '@fnndsc/menu';
+import type { ReferenceValue } from '../lib/parser.js';
+import type { ListingLook, VFSDispatcher } from '@fnndsc/fond';
+import type { ListingItem } from '@fnndsc/menu';
+/**
+ * Who a session is and where: the input a host keys the session by (calypso's
+ * berth name is `user@where`, normalised).
+ *
+ * A disconnected session still has one, so it stays discoverable; each
+ * backend names its own (`where` naming the backend), so two backends'
+ * disconnected sessions never share a name.
+ */
+export interface SessionIdentity {
+    /** The user, exactly as the backend knows them. */
+    readonly user: string;
+    /** Where the session lives: a server URL, or a name for no server. */
+    readonly where: string;
+    /** Whether the session is connected to `where`. */
+    readonly connected: boolean;
+}
+/** What a backend tells the core about the session it serves. */
+export interface BackendSession {
+    /** Prepares the backend's own state (configuration, stored credentials) before the session starts. */
+    init(): Promise<void>;
+    /** Who the session is, connected or not. */
+    identity_get(): Promise<SessionIdentity>;
+    /** The session's user as the backend last knew them, or null when it knows none. */
+    user_get(): Promise<string | null>;
+    /** The session's home: where it begins before it has a working directory of its own. */
+    home_get(): Promise<string>;
+    /** The working directory the identity left, or null when it has none stored. */
+    cwd_load(): Promise<string | null>;
+    /** Stores the working directory for the identity. */
+    cwd_save(path: string): Promise<void>;
+}
+/** What the core knows about the previous command, for the prompt. */
+export interface PromptLastCommand {
+    lastExitCode?: number;
+    lastCommandDurationMs?: number;
+}
+/**
+ * What a daemon heartbeats about the backend's own state, in the wire's
+ * telemetry shape: the index counts, the server's pace, the work in flight.
+ */
+export interface BackendTelemetry {
+    jobs: number;
+    feeds: number;
+    cube?: CubeTelemetry;
+    state?: JobsStateTelemetry;
+}
+/** A name the session answers for in `${name}`, and the dotted names under it. */
+export interface ReferenceSource {
+    /** The name (`feed`); a dotted name under it (`feed.x`) is asked of it too. */
+    readonly name: string;
+    /**
+     * What a name refers to now: its value, null when the session has none
+     * yet, or undefined when it is a dotted name this source does not answer
+     * (the manifest's parameters and the environment are asked next).
+     */
+    readonly resolve: (name: string) => Promise<ReferenceValue | undefined>;
+}
+/** A kind of row a listing numbers, as an index writes it: `@SER3` is the third series. */
+export interface AnswerKindLook {
+    /** Three capital letters. */
+    readonly code: string;
+    /** The kind in words, for a refusal: `a series`. */
+    readonly word: string;
+    /** An index of it, for the refusal that teaches the syntax (`@SER3`); a kind without one is not shown there. */
+    readonly example?: string;
+}
+/** The kinds a verb can be handed by index, beyond those the core declares for it. */
+export interface VerbTakes {
+    readonly verb: string;
+    readonly kinds: ReadonlyArray<string>;
+}
+/**
+ * What a backend does with a command word the registry does not answer.
+ *
+ * The core runs a line in one of two ways: directly, its output going to
+ * the surface, or captured, its output feeding a pipe or a redirect. Each
+ * asks the backend at fixed points, so a backend's words are found where
+ * they always were.
+ */
+export interface BackendFallback {
+    /**
+     * A word the backend runs ahead of the registry on a direct line, and
+     * after the registry's envelope commands on a captured one (ChRIS: a
+     * plugin named with its version). Null when the word is not one.
+     */
+    readonly claim?: (command: string, args: string[]) => Promise<CommandEnvelope | null>;
+    /**
+     * A word nothing else answered. The envelope it returns has been
+     * delivered; null means the backend does not know the word either, and
+     * the core says `command not found`.
+     */
+    readonly unknown?: (command: string, args: string[], captured: boolean) => Promise<CommandEnvelope | null>;
+    /** Help for a word the registry has no page for, or null to let the core say it has none. */
+    readonly help?: (command: string) => Promise<string | null>;
+}
+/** A listing cache: listings kept for a while, each saying whether it is still current. */
+export interface ListingCache {
+    /** A kept listing and whether it is current, or null when none is kept. */
+    cache_get<T = unknown>(path: string): {
+        data: T;
+        fresh: boolean;
+    } | null;
+    /** Keeps a listing. */
+    cache_set<T = unknown>(path: string, data: T): void;
+    /** Forgets one folder's listing: something in it changed. */
+    cache_invalidate?(path: string): void;
+    /** Forgets a folder's listing and every one beneath it: the folder went. */
+    cache_invalidateTree?(path: string): void;
+}
+/** What entering a folder outside the mounts came to, for `cd`. */
+export interface FolderEntry {
+    /** The working directory to stand in, or null when the path is not a folder one can. */
+    readonly cwd: string | null;
+    /** What `cd` shows on its way (a debugging trace). */
+    readonly rendered: string;
+    /** What `cd` says when it cannot, in full; empty to let the core say `No such file or directory`. */
+    readonly renderedErr: string;
+}
+/** The backend's filesystem, as the core's listings, globbing and completion read it. */
+export interface BackendFilesystem {
+    /** Every path goes through it: the backend's mounts and its fallback. The core adds its own mounts. */
+    readonly dispatcher: VFSDispatcher;
+    /** Where listings are kept between reads; absent, every listing is read afresh. */
+    readonly cache?: ListingCache;
+    /** Whether a path's listing may be kept (ChRIS: not under `/proc`, which keeps its own); absent, every path may. */
+    readonly cache_holds?: (path: string) => boolean;
+    /** What a long listing's rows carry beyond the listing (ChRIS: a feed's tags). */
+    readonly longRows_annotate?: (items: ListingItem[]) => Promise<ListingItem[]>;
+    /**
+     * The folders whose links the last walk could not read, taken (and so
+     * cleared): a listing that fails says the path was walked as written.
+     */
+    readonly unreadLinks_take?: () => Promise<string[]>;
+    /** A folder as the filesystem holds it, links followed, for globbing beneath it; absent, the path as given. */
+    readonly path_physical?: (path: string) => Promise<string>;
+    /** Paths that are always folders, entered without asking (beside the mounts and the folders above them). */
+    readonly structural?: ReadonlyArray<string>;
+    /**
+     * Enters a folder outside the mounts (`cd`): whether it is one, and where
+     * the session then stands. Absent, a path that lists is a folder.
+     */
+    readonly folder_enter?: (logicalPath: string, pathArg: string) => Promise<FolderEntry>;
+    /** The title a path segment shows under `pwd --title` (ChRIS: a feed's name), or null for none. */
+    readonly segment_title?: (segment: string) => Promise<string | null>;
+}
+/** What a backend adds to completion. */
+export interface BackendCompletion {
+    /** Command words beyond the registry's (ChRIS: its plugins). */
+    readonly commandWords?: () => Promise<string[]>;
+    /** The `--option` words for a line, or null when the line is not one the backend completes. */
+    readonly options?: (args: string[], word: string) => Promise<string[] | null>;
+    /** Names completed at `/` even when the root's listing lacks them; absent, the core's `usr`. */
+    readonly rootWords?: ReadonlyArray<string>;
+}
+/**
+ * Where a backend's long-running steps come from: one kind of task (ChRIS:
+ * its plugin instances; an infrastructure backend: its install steps).
+ */
+export interface TaskSource {
+    /** Its name, and its folder: `/proc/<id>`. */
+    readonly id: string;
+    /** What an operator reads it as. */
+    readonly label: string;
+    /**
+     * The backend mounts `/proc/<id>` itself (ChRIS's `/proc/jobs`, a tree of
+     * feeds and instances); otherwise the core mounts each task as a folder of
+     * its fields.
+     */
+    readonly mounted?: boolean;
+    /** Its tasks, now. */
+    list(): Promise<Task[]>;
+    /** One task's log, whole; absent, its `logTail` is its log. */
+    log?(id: string): Promise<string | null>;
+}
+/** Administrator credentials, collected by the core from the surface. */
+export interface ElevationCredentials {
+    username: string;
+    password: string;
+}
+/** One backend, as the core sees it. */
+export interface Backend {
+    /** Stable id naming the backend. */
+    readonly id: string;
+    /** The session it serves. */
+    readonly session: BackendSession;
+    /** The session facts a prompt shows, in the wire's prompt context. */
+    readonly prompt?: (last?: PromptLastCommand) => Promise<PromptContext>;
+    /** The daemon's heartbeat about the backend's state; read often, so it is cheap. */
+    readonly telemetry?: () => BackendTelemetry;
+    /** The `${name}` references it answers, beside the core's `cwd`. */
+    readonly references?: ReadonlyArray<ReferenceSource>;
+    /** The kinds of row its listings number; they lead the core's (`FIL`, `DIR`) wherever kinds are listed. */
+    readonly answerKinds?: ReadonlyArray<AnswerKindLook>;
+    /** The kinds its verbs take by index, and those it adds to the core's verbs. */
+    readonly verbTakes?: ReadonlyArray<VerbTakes>;
+    /** What it does with words the registry does not answer. */
+    readonly fallback?: BackendFallback;
+    /** Runs one command with administrator rights (`sudo`); absent, `sudo` is refused. */
+    readonly elevate?: (credentials: ElevationCredentials, run: () => Promise<CommandEnvelope>) => Promise<CommandEnvelope>;
+    /** Watches a subject a surface named (ChRIS: a feed's jobs), on behalf of an owner. */
+    readonly watch?: {
+        readonly set: (subject: string, owner: string, on: boolean) => WatchState | null;
+        readonly release: (owner: string) => void;
+    };
+    /** Reads and writes one file's bytes for a surface, at a path the session resolves. */
+    readonly files?: {
+        readonly read: (path: string) => Promise<Buffer>;
+        readonly write: (path: string, bytes: Buffer) => Promise<void>;
+    };
+    /** Its long-running steps, by kind; the core mounts those that bring no mount of their own under `/proc`. */
+    readonly tasks?: ReadonlyArray<TaskSource>;
+    /** Its filesystem; absent, the session has only the core's own mounts. */
+    readonly vfs?: BackendFilesystem;
+    /** What it adds to completion. */
+    readonly completion?: BackendCompletion;
+    /** How its listings show: the kinds it lists beside the core's, and how a name is coloured. */
+    readonly listingLook?: ListingLook;
+    /** Whether the backend is debugging (error messages keep their function stamp), or null before it can say. */
+    readonly debug_get?: () => boolean | null;
+    /** Turns the backend's debugging on or off. */
+    readonly debug_set?: (on: boolean) => void;
+}
+/**
+ * Installs the session's backend. The last install wins; a host installs
+ * before the engine boots.
+ *
+ * @param backend - The backend the session runs over.
+ */
+export declare function backend_install(backend: Backend): void;
+/**
+ * The installed backend, or null before one is installed: for a reader that
+ * has an answer without one (the core's own references and kinds).
+ *
+ * @returns The backend, or null.
+ */
+export declare function backendInstalled_get(): Backend | null;
+/**
+ * The installed backend.
+ *
+ * @returns The backend the session runs over.
+ * @throws Error when no backend is installed: the session cannot run without one.
+ */
+export declare function backend_get(): Backend;

package/dist/core/backend.js

@@ -0,0 +1,32 @@
+let installed = null;
+/**
+ * Installs the session's backend. The last install wins; a host installs
+ * before the engine boots.
+ *
+ * @param backend - The backend the session runs over.
+ */
+export function backend_install(backend) {
+    installed = backend;
+}
+/**
+ * The installed backend, or null before one is installed: for a reader that
+ * has an answer without one (the core's own references and kinds).
+ *
+ * @returns The backend, or null.
+ */
+export function backendInstalled_get() {
+    return installed;
+}
+/**
+ * The installed backend.
+ *
+ * @returns The backend the session runs over.
+ * @throws Error when no backend is installed: the session cannot run without one.
+ */
+export function backend_get() {
+    if (installed === null) {
+        throw new Error('brasa: no backend installed; install one with backend_install before the engine boots');
+    }
+    return installed;
+}
+//# sourceMappingURL=backend.js.map

package/dist/core/backend.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"backend.js","sourceRoot":"","sources":["../../src/core/backend.ts"],"names":[],"mappings":"AA6PA,IAAI,SAAS,GAAmB,IAAI,CAAC;AAErC;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAAC,OAAgB;IAC9C,SAAS,GAAG,OAAO,CAAC;AACtB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB;IAClC,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,WAAW;IACzB,IAAI,SAAS,KAAK,IAAI,EAAE,CAAC;QACvB,MAAM,IAAI,KAAK,CAAC,uFAAuF,CAAC,CAAC;IAC3G,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/dist/core/commandOrder.d.ts

@@ -0,0 +1,16 @@
+/**
+ * @file The order commands list in: tab completion offers matches in this order.
+ *
+ * Kept explicitly, apart from which group registers a name, so registering the
+ * core and a backend's commands separately does not reorder what the shell
+ * offers. A name registered but not listed here lists after these, in
+ * registration order.
+ *
+ * @module
+ */
+/** Help topics, which are also the `/bin` builtins and the completion candidates. */
+export declare const HELP_ORDER: string[];
+/** Names answered by an envelope handler. */
+export declare const ENVELOPE_ORDER: string[];
+/** Names answered by a plain handler. */
+export declare const PLAIN_ORDER: string[];

package/dist/core/commandOrder.js

@@ -0,0 +1,17 @@
+/**
+ * @file The order commands list in: tab completion offers matches in this order.
+ *
+ * Kept explicitly, apart from which group registers a name, so registering the
+ * core and a backend's commands separately does not reorder what the shell
+ * offers. A name registered but not listed here lists after these, in
+ * registration order.
+ *
+ * @module
+ */
+/** Help topics, which are also the `/bin` builtins and the completion candidates. */
+export const HELP_ORDER = ["2048", "user", "sudo", "ls", "cd", "netstat", "pwd", "cat", "edit", "setfacl", "getfacl", "chmod", "setfattr", "getfattr", "rm", "cp", "mv", "touch", "config", "mkdir", "rmdir", "upload", "download", "connect", "logout", "plugin", "plugins", "feed", "feeds", "files", "links", "dirs", "pipeline", "pacs", "pacs query", "pacs pull", "pacs connect", "pacs disconnect", "pacs list", "pacsservers", "pacsqueries", "pacsretrieve", "exit", "context", "whoami", "version", "id", "fortune", "cowsay", "cowthink", "figlet", "banner", "lolcat", "rev", "tac", "yes", "seq", "factor", "primes", "shuf", "roll", "rot13", "morse", "calc", "units", "who", "uptime", "ping", "chrisfetch", "say", "wtf", "file", "xxd", "strings", "sha256sum", "md5sum", "qr", "pom", "stardate", "ddate", "sunrise", "timer", "leave", "stopwatch", "sl", "cmatrix", "rain", "asciiquarium", "tetris", "snake", "quiz", "hangman", "notes", "weather", "motd", "date", "cal", "whereami", "proc", "prompt", "physicalmode", "timing", "debug", "parametersofplugin", "tree", "du", "store", "compute", "tag", "tags", "record", "play", "expect", "gather", "group", "groups", "pluginmeta", "pluginmetas", "plugininstance", "plugininstances", "workflow", "workflows", "meta", "metas", "instance", "instances", "job", "jobs", "help", "!", "dcm", "image", "cubepath", "query", "pull"];
+/** Names answered by an envelope handler. */
+export const ENVELOPE_ORDER = ["2048", "cat", "cd", "cp", "mv", "rm", "setfacl", "getfacl", "chmod", "setfattr", "getfattr", "mkdir", "rmdir", "touch", "pwd", "netstat", "id", "whoami", "whereami", "timing", "physicalmode", "debug", "version", "fortune", "cowsay", "cowthink", "figlet", "banner", "lolcat", "rev", "tac", "yes", "seq", "factor", "primes", "shuf", "roll", "rot13", "morse", "calc", "units", "who", "uptime", "ping", "chrisfetch", "say", "wtf", "file", "xxd", "strings", "sha256sum", "md5sum", "qr", "pom", "stardate", "ddate", "sunrise", "timer", "leave", "stopwatch", "sl", "cmatrix", "rain", "asciiquarium", "tetris", "snake", "quiz", "hangman", "weather", "motd", "notes", "date", "cal", "ls", "tree", "du", "help", "proc", "logout", "cubepath", "dcm", "image", "query", "feed", "feeds", "compute", "computes", "tag", "tags", "expect", "play", "record", "gather", "group", "groups", "user", "users", "pluginmeta", "pluginmetas", "meta", "metas", "plugininstance", "plugininstances", "instance", "instances", "job", "jobs", "workflow", "workflows", "files", "links", "dirs", "context", "parametersofplugin", "plugin", "plugins", "pacsservers", "pacsqueries", "pacsretrieve", "connect", "upload", "download", "store", "edit", "config", "pacs", "pull", "pipeline", "pipelines"];
+/** Names answered by a plain handler. */
+export const PLAIN_ORDER = ["2048", "connect", "logout", "cd", "ls", "pwd", "netstat", "cat", "rm", "setfacl", "getfacl", "chmod", "setfattr", "getfattr", "cp", "mv", "touch", "mkdir", "rmdir", "upload", "pacs", "pipeline", "pipelines", "pull", "query", "cubepath", "dcm", "image", "download", "edit", "config", "context", "parametersofplugin", "physicalmode", "timing", "id", "whoami", "whereami", "debug", "fortune", "cowsay", "cowthink", "figlet", "banner", "lolcat", "rev", "tac", "yes", "seq", "factor", "primes", "shuf", "roll", "rot13", "morse", "calc", "units", "who", "uptime", "ping", "chrisfetch", "say", "wtf", "file", "xxd", "strings", "sha256sum", "md5sum", "qr", "pom", "stardate", "ddate", "sunrise", "timer", "leave", "stopwatch", "sl", "cmatrix", "rain", "asciiquarium", "tetris", "snake", "quiz", "hangman", "weather", "motd", "notes", "date", "cal", "help", "proc", "tree", "du", "store", "plugin", "plugins", "feed", "feeds", "compute", "computes", "tag", "tags", "expect", "play", "record", "gather", "group", "groups", "pluginmeta", "pluginmetas", "meta", "metas", "plugininstance", "plugininstances", "instance", "instances", "job", "jobs", "workflow", "workflows", "files", "links", "dirs", "pacsservers", "pacsqueries", "pacsretrieve"];
+//# sourceMappingURL=commandOrder.js.map

package/dist/core/commandOrder.js.map

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

package/dist/core/commandRegistry.d.ts

@@ -0,0 +1,120 @@
+/**
+ * @file The command registry: every name the engine answers in-process, and the
+ * handler that answers it.
+ *
+ * A command registers as an envelope handler (it returns its outcome as an
+ * envelope) or a plain handler (it may print, and returns an envelope or
+ * nothing). Dispatch, the capture path and the pipe's "is this a builtin" test
+ * read the registry, never a table of their own. So do `help`, the `/bin`
+ * builtin list and command completion, through the help a command registers.
+ *
+ * Handlers are kept in plain records and looked up by index, exactly as the
+ * dispatch tables were: a name is a builtin when it is `in` a record. A record
+ * inherits from `Object.prototype`, so a name such as `toString` counts as a
+ * builtin too; that is how the tables behaved, and changing it is a decision of
+ * its own, not a side effect of moving the lookup here.
+ *
+ * Listing order is kept explicitly (`commandOrder_set`), apart from which
+ * group registered a name, so the core's and a backend's commands registering
+ * separately do not reorder what the shell offers; an unlisted name lists
+ * after, in registration order. A later registration of a name replaces the
+ * earlier.
+ *
+ * @module
+ */
+import type { CommandEnvelope } from '@fnndsc/menu';
+/** A builtin that returns its outcome as an envelope. */
+export type EnvelopeHandler = (args: string[]) => Promise<CommandEnvelope>;
+/** A builtin that may print, and returns an envelope or nothing. */
+export type CommandHandler = (args: string[]) => Promise<void | CommandEnvelope>;
+/** A command's help: what `help <name>` shows, and what the listings summarise. */
+export interface CommandHelp {
+    usage: string;
+    /** One line for listings; the description stands in when there is none. */
+    summary?: string;
+    description: string;
+    subcommands?: string[];
+    options?: string[];
+    examples?: string[];
+}
+/** A group of commands registered together. */
+export interface CommandGroup {
+    /** Commands answered by an envelope handler. */
+    envelope?: Record<string, EnvelopeHandler>;
+    /** Commands answered by a plain handler. */
+    plain?: Record<string, CommandHandler>;
+    /**
+     * Help, by name. Its names are the builtins `/bin` lists and the shell
+     * completes, in registration order.
+     */
+    help?: Record<string, CommandHelp>;
+}
+/** Who registers a group: the core, or the session's backend. */
+export type CommandOwner = 'core' | 'backend';
+/**
+ * Every envelope handler registered, by name: the record the engine's
+ * `ENVELOPE_HANDLERS` export names. Read through {@link envelopeHandler_get}.
+ */
+export declare const ENVELOPE_HANDLERS: Readonly<Record<string, EnvelopeHandler>>;
+/**
+ * Every plain handler registered, by name: the record the engine's
+ * `COMMAND_HANDLERS` export names. Read through {@link plainHandler_get}.
+ */
+export declare const COMMAND_HANDLERS: Readonly<Record<string, CommandHandler>>;
+/**
+ * Sets the order names list in, by kind, apart from which group registered
+ * them: a registered name in the order lists there, and any other after,
+ * in registration order.
+ *
+ * @param order - The names, by kind, in listing order.
+ */
+export declare function commandOrder_set(order: {
+    envelope?: string[];
+    plain?: string[];
+    help?: string[];
+}): void;
+/**
+ * Registers a group of commands. The core's come first; a backend's are
+ * added beside them and may not replace one (a backend never overrides a
+ * core command).
+ *
+ * @param group - The commands, by name, in the order they list.
+ * @param owner - Whose commands they are: the core's, or a backend's.
+ * @throws {Error} When a backend's group names a core command.
+ */
+export declare function commands_register(group: CommandGroup, owner?: CommandOwner): void;
+/**
+ * The envelope handler a name reaches, by index (as the tables were read).
+ *
+ * @param name - The command name.
+ * @returns The handler, or undefined.
+ */
+export declare function envelopeHandler_get(name: string): EnvelopeHandler | undefined;
+/**
+ * The plain handler a name reaches, by index (as the tables were read).
+ *
+ * @param name - The command name.
+ * @returns The handler, or undefined.
+ */
+export declare function plainHandler_get(name: string): CommandHandler | undefined;
+/**
+ * Whether a name is answered in-process, by either kind of handler: the pipe's
+ * test for running a segment in the engine rather than on the host.
+ *
+ * @param name - The command name.
+ * @returns True when the name is `in` either record.
+ */
+export declare function builtinCommand_has(name: string): boolean;
+/** @returns The names answered by an envelope handler, in listing order. */
+export declare function envelopeCommand_names(): string[];
+/** @returns The names answered by a plain handler, in listing order. */
+export declare function plainCommand_names(): string[];
+/**
+ * A name's help, by index (as the help record was read).
+ *
+ * @param name - The command or topic name.
+ * @returns The help, or undefined.
+ */
+export declare function commandHelpEntry_get(name: string): CommandHelp | undefined;
+/** @returns The names that have help, in listing order: `/bin`'s builtins and the shell's completions. */
+export declare function helpTopic_names(): string[];