@fnndsc/brasa 0.56.4 → 0.57.0

package/dist/chris/binDeclarations.d.ts

@@ -0,0 +1,312 @@
+/**
+ * @file The declaration of a `/bin` line: a plugin's or a pipeline's, made
+ * from what CUBE declares of it, so the line is parsed, completed, refused
+ * and described as a builtin's is.
+ *
+ * CUBE owns a plugin's parameters and a pipeline's nodes; nothing here
+ * declares them a second time. A plugin's declaration is made from its
+ * parameters (flag, short flag, type, optional, default, help): a `bool`
+ * parameter is a switch, `int` and `float` are numbers, `path` and
+ * `unextpath` are CFS paths, anything else a word. A pipeline's is made
+ * from its manifest: one `--<node>.<field>` option for every field of every
+ * node, the node named by its title when that is unique and shell-safe and
+ * always by `@<piping id>`. Beside them stand the session's own options of
+ * a `/bin` line (`--detach`, `--parameters`, `--diagram`, …), which win a
+ * name both claim, and the operands: the line's input paths, which glob.
+ *
+ * A declaration is made when the session first needs it and kept, by the
+ * `/bin` entry it is made for: a plugin's carries its version
+ * (`pl-dircopy-v2.1.1`), a pipeline's its id in this CUBE
+ * (`PHI_detection_id12`), so a new version or a new registration is a new
+ * declaration.
+ *
+ * A plugin's line ends, after a lone `--`, with the run's own `key=value`
+ * context (`-- feed_title="T"`), which the line keeps apart before it is
+ * parsed.
+ *
+ * Key components:
+ * - pluginDeclaration_make / pipelineDeclaration_make: the pure builders.
+ * - binDeclaration_get: the declaration of a word `/bin` answers, kept once made.
+ * - pluginLine_parse / pipelineLine_parse: a line's words to its typed reading.
+ *
+ * Typical usage:
+ * ```ts
+ * const declaration: CommandDeclaration | null = await binDeclaration_get('pl-dircopy');
+ * const parsed: PluginLineParse = await pluginLine_parse('pl-dircopy-v2.1.1', ['~/uploads', '--', 'feed_title=T']);
+ * ```
+ *
+ * Dependencies: the parser and the declaration types; CUBE through cumin and
+ * salsa (loaded when a declaration is made); `/bin` for which entry a word names.
+ *
+ * @module
+ */
+import type { PipelineManifest } from '@fnndsc/salsa';
+import type { CommandEnvelope } from '@fnndsc/menu';
+import type { CommandArguments, CommandDeclaration, CommandGrammar } from '../core/commandDeclaration.js';
+import { type ParsedArguments } from '../core/commandParse.js';
+/** One parameter of a plugin, as CUBE declares it. */
+export interface PluginParameterSpec {
+    /** Its name, as CUBE stores it. */
+    readonly name: string;
+    /** Its type: `str`, `int`, `float`, `bool`, `path`, `unextpath` (or their long spellings). */
+    readonly type: string;
+    /** Whether a run may leave it out. */
+    readonly optional: boolean;
+    /** Its default, when it declares one. */
+    readonly default?: unknown;
+    /** One line of help. */
+    readonly help?: string;
+    /** Its flag as typed: `--dir`. */
+    readonly flag: string;
+    /** Its one-letter flag, when it has one: `-d`. */
+    readonly shortFlag?: string;
+}
+/** One plugin version, as its declaration is made from it. */
+export interface PluginSpec {
+    /** The plugin's name. */
+    readonly name: string;
+    /** Its version. */
+    readonly version: string;
+    /** Its kind: `ds`, `fs` or `ts`. */
+    readonly kind: string;
+    /** Its title, when it has one. */
+    readonly title?: string;
+    /** What it does, when it says. */
+    readonly description?: string;
+    /** Every parameter, in CUBE's order. */
+    readonly parameters: readonly PluginParameterSpec[];
+}
+/** A plugin line, read: its input, its parameters, its context, and what the session does with it. */
+export interface PluginLine {
+    /** The operand words, as typed: paths, `as <subject>`, and any bare `key=value`. */
+    readonly operands: readonly string[];
+    /** The plugin's parameters given, by flag name (`dir`), each its value. */
+    readonly parameters: Readonly<Record<string, string | number | boolean>>;
+    /** The run's context words, after a lone `--` (`feed_title=T`). */
+    readonly context: readonly string[];
+    /** Return the run's handle at once rather than wait for it. */
+    readonly detach: boolean;
+    /** A look at the plugin instead of a run: its parameters, its README, or its raw README. */
+    readonly inspect: 'parameters' | 'readme' | 'readmeRaw' | null;
+}
+/** What reading a plugin line came to. */
+export type PluginLineParse = {
+    readonly ok: true;
+    readonly line: PluginLine;
+} | {
+    readonly ok: false;
+    readonly refusal: string;
+};
+/** The ways a pipeline line asks to look at the pipeline rather than run it. */
+export type PipelineLook = 'diagram' | 'signalflow' | 'manifest' | 'nodes' | 'source' | 'help';
+/** One override of a pipeline node, as `pipeline run` takes it. */
+export interface PipelineLineBinding {
+    /** The node: its title, or `@<piping id>`. */
+    readonly node: string;
+    /** The field: a parameter or an execution control. */
+    readonly field: string;
+    /** The value. */
+    readonly value: unknown;
+}
+/** A pipeline line, read. */
+export interface PipelineLine {
+    /** The operand words: the input paths, as typed. */
+    readonly operands: readonly string[];
+    /** A look at the pipeline instead of a run, or null for a run. */
+    readonly look: PipelineLook | null;
+    /** Draw the diagram with each node's stored arguments. */
+    readonly withArguments: boolean;
+    /** Draw the diagram as SignalFlow YAML. */
+    readonly signalflow: boolean;
+    /** The compute resource every node runs on, when given. */
+    readonly compute?: string;
+    /** The instance the run attaches to, when given. */
+    readonly previous?: number;
+    /** A CFS file of overrides, when given. */
+    readonly paramFile?: string;
+    /** The node overrides given. */
+    readonly bindings: readonly PipelineLineBinding[];
+    /** Return the run's handles at once. */
+    readonly detach: boolean;
+    /** Echo every parameter of every piping. */
+    readonly verbose: boolean;
+}
+/** What reading a pipeline line came to. */
+export type PipelineLineParse = {
+    readonly ok: true;
+    readonly line: PipelineLine;
+} | {
+    readonly ok: false;
+    readonly refusal: string;
+};
+/** The `/bin` entry a word names: a plugin version, or a pipeline. */
+export type BinEntry = {
+    readonly kind: 'plugin';
+    readonly executable: string;
+} | {
+    readonly kind: 'pipeline';
+    readonly name: string;
+};
+/**
+ * A plugin version's declaration, made from what CUBE declares of it: its
+ * `/bin` entry's name, its input operand, the session's options and one per
+ * parameter, and help from its title and description.
+ *
+ * @param spec - The plugin version.
+ * @param handler - What runs a parsed line (the run, or a test's stand-in).
+ * @returns The declaration.
+ *
+ * @example
+ * ```ts
+ * const declaration = pluginDeclaration_make({ name: 'pl-dircopy', version: '2.1.1', kind: 'fs', parameters: [{ name: 'dir', type: 'path', optional: false, flag: '--dir' }] }, run);
+ * declaration.grammar.options?.['dir']?.value?.kind; // 'cfsPath'
+ * ```
+ */
+export declare function pluginDeclaration_make(spec: PluginSpec, handler: (args: CommandArguments<CommandGrammar>) => Promise<CommandEnvelope>): CommandDeclaration;
+/**
+ * A pipeline's declaration, made from its manifest: its `/bin` entry's
+ * name, its input operand, the session's options and one `--<node>.<field>`
+ * option for every field of every node.
+ *
+ * @param binName - The pipeline's `/bin` name (`PHI_detection_id12`).
+ * @param manifest - Its manifest, with the nodes' parameter definitions.
+ * @param handler - What runs a parsed line.
+ * @returns The declaration.
+ *
+ * @example
+ * ```ts
+ * const declaration = pipelineDeclaration_make('PHI_id3', manifest, run);
+ * Object.keys(declaration.grammar.options ?? {}); // ['diagram', …, 'segment.threshold', '@41.threshold', …]
+ * ```
+ */
+export declare function pipelineDeclaration_make(binName: string, manifest: PipelineManifest, handler: (args: CommandArguments<CommandGrammar>) => Promise<CommandEnvelope>): CommandDeclaration;
+/** A parsed line as these readers take it: its operands and options by name, whatever grammar parsed it. */
+type LineRead = Pick<ParsedArguments, 'operands' | 'options'> | CommandArguments<CommandGrammar>;
+/**
+ * A plugin line, parsed: the typed reading of the line a declaration parsed.
+ *
+ * @param args - The parsed line.
+ * @param context - The run's context words.
+ * @returns The plugin line.
+ *
+ * @example
+ * ```ts
+ * pluginLine_read(parsed.args, ['feed_title=T']).parameters; // { dir: '/home/a/uploads' }
+ * ```
+ */
+export declare function pluginLine_read(args: LineRead, context?: readonly string[]): PluginLine;
+/**
+ * Parses a plugin's line against a declaration: the context split off at
+ * the first lone `--`, the rest parsed as a builtin's line is.
+ *
+ * @param declaration - The plugin's declaration.
+ * @param args - The words after the `/bin` name, carrying their shell words when a line gave them.
+ * @returns The plugin line, or the refusal (`pl-dircopy-v2.1.1: unrecognized option '--x'; usage: …`).
+ *
+ * @example
+ * ```ts
+ * const parsed: PluginLineParse = await pluginWords_parse(declaration, ['~/uploads', '--', 'feed_title=T']);
+ * ```
+ */
+export declare function pluginWords_parse(declaration: CommandDeclaration, args: readonly string[]): Promise<PluginLineParse>;
+/**
+ * A pipeline line, parsed: the look it asks for or the run's options and
+ * node overrides.
+ *
+ * @param args - The parsed line.
+ * @returns The pipeline line.
+ *
+ * @example
+ * ```ts
+ * pipelineLine_read(parsed.args).bindings; // [{ node: 'segment', field: 'threshold', value: 0.5 }]
+ * ```
+ */
+export declare function pipelineLine_read(args: LineRead): PipelineLine;
+/**
+ * Parses a pipeline's line against a declaration.
+ *
+ * @param declaration - The pipeline's declaration.
+ * @param args - The words after the `/bin` name.
+ * @returns The pipeline line, or the refusal.
+ *
+ * @example
+ * ```ts
+ * const parsed: PipelineLineParse = await pipelineWords_parse(declaration, ['--segment.threshold', '0.5']);
+ * ```
+ */
+export declare function pipelineWords_parse(declaration: CommandDeclaration, args: readonly string[]): Promise<PipelineLineParse>;
+/**
+ * Forgets every declaration made, so the next is read from CUBE again.
+ *
+ * @example
+ * ```ts
+ * binDeclarations_forget();
+ * ```
+ */
+export declare function binDeclarations_forget(): void;
+/**
+ * The `/bin` entry a word names: a plugin by its full `/bin` name, a
+ * pipeline by its `/bin` name or its own, or a bare plugin name's highest
+ * version.
+ *
+ * @param command - The word.
+ * @returns The entry, or null when `/bin` names none.
+ *
+ * @example
+ * ```ts
+ * await binEntry_resolve('pl-dircopy'); // { kind: 'plugin', executable: 'pl-dircopy-v2.1.1' }
+ * ```
+ */
+export declare function binEntry_resolve(command: string): Promise<BinEntry | null>;
+/**
+ * The declaration of a word `/bin` answers, made from CUBE the first time
+ * and kept by its entry: what completion, help and the schema read of a
+ * plugin or a pipeline, and what its line is parsed against.
+ *
+ * @param command - The word: a plugin's `/bin` name or bare name, or a pipeline's.
+ * @returns The declaration, or null when the word names nothing in `/bin` or CUBE cannot say.
+ *
+ * @example
+ * ```ts
+ * (await binDeclaration_get('pl-dircopy'))?.name; // 'pl-dircopy-v2.1.1'
+ * ```
+ */
+export declare function binDeclaration_get(command: string): Promise<CommandDeclaration | null>;
+/**
+ * The declaration of one plugin version, by its full `/bin` name.
+ *
+ * @param executable - `<name>-v<version>`.
+ * @returns The declaration, or null when CUBE cannot say.
+ *
+ * @example
+ * ```ts
+ * await pluginDeclaration_get('pl-dircopy-v2.1.1');
+ * ```
+ */
+export declare function pluginDeclaration_get(executable: string): Promise<CommandDeclaration | null>;
+/**
+ * The declaration of one pipeline, by its `/bin` name.
+ *
+ * @param name - The pipeline's `/bin` name.
+ * @returns The declaration, or null when CUBE cannot say.
+ *
+ * @example
+ * ```ts
+ * await pipelineDeclaration_get('PHI_detection_id12');
+ * ```
+ */
+export declare function pipelineDeclaration_get(name: string): Promise<CommandDeclaration | null>;
+/**
+ * The fields `--<node>.<field>` names for a pipeline, for `pipeline run`'s
+ * completion: every option of its declaration that overrides a node.
+ *
+ * @param pipeline - The pipeline as the line names it.
+ * @returns The names, without the dashes; none when the pipeline cannot be read.
+ *
+ * @example
+ * ```ts
+ * await pipelineNodeOptions_list('PHI_detection'); // ['segment.threshold', '@41.threshold', …]
+ * ```
+ */
+export declare function pipelineNodeOptions_list(pipeline: string): Promise<string[]>;
+export {};