@fnndsc/brasa 0.56.3 → 0.57.0

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

@@ -15,9 +15,57 @@
  *
  * @module
  */
+import type { PipelineInvocationBinding } from '@fnndsc/salsa';
 import { type RunSettlement } from './runWait.js';
 import type { PipelineScheduled } from '../../api/models.js';
 import { type CommandEnvelope } from '@fnndsc/menu';
+/**
+ * Handles `pipeline info <name|id>`.
+ *
+ * @param nameOrId - The pipeline.
+ * @returns Command envelope whose status matches resolution and manifest fetching.
+ *
+ * @example
+ * ```ts
+ * await pipelineInfo_handle('PHI_detection');
+ * ```
+ */
+export declare function pipelineInfo_handle(nameOrId: string): Promise<CommandEnvelope>;
+/** One pipeline run, as a line asks for it: the pipeline, where it attaches, its overlays, and how the line holds it. */
+export interface PipelineRunRequest {
+    /** The pipeline: its name, id or `/bin` name. */
+    readonly pipeline: string;
+    /** The compute resource every node runs on, when given. */
+    readonly compute?: string;
+    /** The instance the run attaches to; absent, the feed node the session stands in. */
+    readonly previous?: number;
+    /** A CFS file of sparse YAML overrides, when given. */
+    readonly paramFile?: string;
+    /** The node overrides, `--<node>.<field> <value>`. */
+    readonly bindings: readonly PipelineInvocationBinding[];
+    /** Return the handles at once rather than wait for the run. */
+    readonly detach: boolean;
+    /** Echo every parameter of every piping. */
+    readonly verbose: boolean;
+    /** Resolve the run and print it, creating nothing (`whatif`). */
+    readonly dry: boolean;
+    /** A dry run on a feed that would be rooted first, so no node exists to attach to. */
+    readonly dryNewFeed: boolean;
+}
+/**
+ * Runs one pipeline: from the instance the request names or the feed node
+ * the session stands in, with the overlays it gives; the resolved call is
+ * echoed first, and a dry run stops there.
+ *
+ * @param request - The run.
+ * @returns Command envelope whose status matches Workflow creation.
+ *
+ * @example
+ * ```ts
+ * await pipelineRun_execute({ pipeline: 'PHI_detection', bindings: [], detach: false, verbose: false, dry: true, dryNewFeed: false });
+ * ```
+ */
+export declare function pipelineRun_execute(request: PipelineRunRequest): Promise<CommandEnvelope>;
 /** The model kind a scheduled pipeline travels under. */
 export declare const PIPELINE_SCHEDULED_KIND: string;
 /**
@@ -34,8 +82,189 @@ export declare const PIPELINE_SCHEDULED_KIND: string;
  */
 export declare function pipelineScheduled_make(pipelineName: string, workflowId: number, feedId: number, instanceIds: ReadonlyArray<number>, settlement: RunSettlement | null, newFeed?: boolean): PipelineScheduled;
 /**
- * Manages ChRIS pipeline registration, inspection, and execution.
+ * Handles `pipeline source <name|id>`.
+ *
+ * @param nameOrId - The pipeline.
+ * @returns Command envelope whose status matches source retrieval.
+ *
+ * @example
+ * ```ts
+ * await pipelineSource_handle('PHI_detection');
+ * ```
+ */
+export declare function pipelineSource_handle(nameOrId: string): Promise<CommandEnvelope>;
+/**
+ * Handles `pipeline manifest <name|id|slug>`.
+ *
+ * @param specifier - The pipeline, its words joined.
+ * @returns Complete registered invocation manifest as serializable YAML.
+ *
+ * @example
+ * ```ts
+ * await pipelineManifestCommand_handle('PHI_detection');
+ * ```
+ */
+export declare function pipelineManifestCommand_handle(specifier: string): Promise<CommandEnvelope>;
+/**
+ * Handles shallow and SignalFlow pipeline diagram output.
+ *
+ * @param specifier - The pipeline, its words joined.
+ * @param withArguments - Each node's stored arguments inline.
+ * @param signalflow - SignalFlow YAML instead of the tree.
+ * @returns The diagram, or the refusal.
+ *
+ * @example
+ * ```ts
+ * await pipelineDiagramCommand_handle('PHI_detection', false, true);
+ * ```
+ */
+export declare function pipelineDiagramCommand_handle(specifier: string, withArguments: boolean, signalflow: boolean): Promise<CommandEnvelope>;
+/**
+ * `pipeline <list|search|inspect|info|manifest|run|source|diagram> …`: the
+ * declaration. `pipelines` is the same command, and a read.
+ *
+ * @example
+ * ```ts
+ * commands_register({ declarations: [pipelineCommand] }, 'backend');
+ * ```
+ */
+export declare const pipelineCommand: import("../../core/commandDeclaration.js").CommandDeclaration<{
+    readonly bare: {
+        readonly summary: "Name the subcommands, and the feed node a run here starts from";
+    };
+    readonly subcommands: {
+        readonly list: {
+            readonly summary: "List the registered pipelines";
+            readonly operands: readonly [{
+                readonly name: "search";
+                readonly kind: "word";
+                readonly optional: true;
+                readonly summary: "Only those whose name holds this";
+            }];
+        };
+        readonly search: {
+            readonly summary: "List the pipelines whose name holds a word (list <word>)";
+            readonly operands: readonly [{
+                readonly name: "term";
+                readonly kind: "word";
+                readonly optional: true;
+                readonly summary: "The word";
+            }];
+        };
+        readonly inspect: {
+            readonly summary: "Name the fields a pipeline has";
+        };
+        readonly info: {
+            readonly summary: "Show a pipeline's nodes, plugins and topology";
+            readonly operands: readonly [{
+                readonly name: "pipeline";
+                readonly kind: "pipeline";
+                readonly summary: "The pipeline: its name, its id, or its /bin name";
+            }];
+        };
+        readonly manifest: {
+            readonly summary: "Emit the complete registered invocation YAML";
+            readonly operands: readonly [{
+                readonly name: "pipeline";
+                readonly kind: "pipeline";
+                readonly repeat: true;
+                readonly summary: "The pipeline: its name (in several words, joined), its id, or its /bin name";
+            }];
+        };
+        readonly run: {
+            readonly summary: "Run a pipeline from the feed node you are in, and wait for it";
+            readonly operands: readonly [{
+                readonly name: "pipeline";
+                readonly kind: "pipeline";
+                readonly summary: "The pipeline: its name, its id, or its /bin name";
+            }];
+            readonly options: {
+                readonly compute: {
+                    readonly long: "compute";
+                    readonly summary: "Run every node on this compute resource";
+                    readonly value: {
+                        readonly name: "resource";
+                        readonly kind: "compute";
+                    };
+                };
+                readonly previous: {
+                    readonly long: "previous";
+                    readonly summary: "Start from this instance (default: the feed node you are in)";
+                    readonly value: {
+                        readonly name: "instance";
+                        readonly kind: "int";
+                        readonly min: 1;
+                    };
+                };
+                readonly paramFile: {
+                    readonly long: "paramFile";
+                    readonly summary: "Apply one sparse YAML invocation overlay, a CFS file";
+                    readonly value: {
+                        readonly name: "file";
+                        readonly kind: "cfsPath";
+                    };
+                };
+                readonly detach: {
+                    readonly long: "detach";
+                    readonly summary: "Return the instance ids at once, without waiting";
+                };
+                readonly verbose: {
+                    readonly long: "verbose";
+                    readonly summary: "Echo every parameter of every piping before the run";
+                };
+                readonly bindings: {
+                    readonly long: "<node>.<field>";
+                    readonly summary: "Override one parameter or execution control of one node (@<piping id> names a node whose title is ambiguous)";
+                    readonly value: {
+                        readonly name: "value";
+                        readonly kind: "word";
+                    };
+                    readonly family: {
+                        readonly pattern: RegExp;
+                        readonly names_list: (operands: readonly string[]) => Promise<string[]>;
+                    };
+                };
+            };
+        };
+        readonly source: {
+            readonly summary: "Show the pipeline YAML source";
+            readonly operands: readonly [{
+                readonly name: "pipeline";
+                readonly kind: "pipeline";
+                readonly summary: "The pipeline: its name, its id, or its /bin name";
+            }];
+        };
+        readonly diagram: {
+            readonly summary: "Draw the pipeline as a shallow tree";
+            readonly operands: readonly [{
+                readonly name: "pipeline";
+                readonly kind: "pipeline";
+                readonly repeat: true;
+                readonly summary: "The pipeline: its name (in several words, joined), its id, or its /bin name";
+            }];
+            readonly options: {
+                readonly withargs: {
+                    readonly long: "withargs";
+                    readonly summary: "Each node's stored non-null arguments inline";
+                };
+                readonly signalflow: {
+                    readonly long: "signalflow";
+                    readonly summary: "Emit SignalFlow YAML instead of the tree";
+                };
+            };
+        };
+    };
+}>;
+/**
+ * Manages ChRIS pipeline registration, inspection, and execution: a
+ * `pipeline` line over words already split, through the declaration.
+ *
+ * @param args - The words after `pipeline`.
+ * @returns The answer, or the refusal of a bad line.
  *
- * @param args - Command arguments.
+ * @example
+ * ```ts
+ * await builtin_pipeline(['run', 'PHI_detection', '--previous', '42']);
+ * ```
  */
 export declare function builtin_pipeline(args: string[]): Promise<CommandEnvelope>;