@fnndsc/salsa 4.4.3 → 4.5.0

package/dist/plugins/plugin_docker.d.ts

@@ -0,0 +1,90 @@
+/**
+ * @file Reading a plugin's descriptor out of its container image.
+ *
+ * The last way `plugin add` finds a descriptor: pull the image (or use the
+ * local copy) and ask it, trying the three ways ChRIS plugins have printed
+ * one over the years, in chrisomatic's order — `chris_plugin_info` with the
+ * image named, `chris_plugin_info` bare, and the old chrisapp `<CMD> --json`.
+ *
+ * Every docker call is an argument vector run without a shell: an image
+ * reference is operator input and never reaches a command line as text.
+ *
+ * Key components:
+ * - DockerRun: the seam that runs one docker command (tests stub it).
+ * - docker_isAvailable: whether a docker daemon answers.
+ * - dockerImage_ensure: the image locally, pulled when absent.
+ * - descriptorFromImage_extract: the image's descriptor JSON, by the three ways.
+ *
+ * Typical usage:
+ * ```ts
+ * if (await docker_isAvailable() && await dockerImage_ensure(image)) {
+ *   const descriptor: Record<string, unknown> | null = await descriptorFromImage_extract(image);
+ * }
+ * ```
+ *
+ * Dependencies: Node.js `child_process`; a `docker` CLI on the host.
+ *
+ * @module
+ */
+/** What one docker command answered. */
+export interface DockerAnswer {
+    /** True when the command exited zero. */
+    readonly ok: boolean;
+    /** Its standard output, trimmed. */
+    readonly stdout: string;
+    /** Its standard error or failure message, trimmed. */
+    readonly stderr: string;
+}
+/** Runs one docker command from its argument vector. */
+export type DockerRun = (args: readonly string[]) => Promise<DockerAnswer>;
+/**
+ * Runs `docker` with an argument vector, no shell.
+ *
+ * @param args - The arguments after `docker`.
+ * @returns What it answered; never throws.
+ *
+ * @example
+ * ```ts
+ * const answer: DockerAnswer = await docker_run(['image', 'inspect', 'alpine']);
+ * ```
+ */
+export declare const docker_run: DockerRun;
+/**
+ * Reports whether a docker daemon answers.
+ *
+ * @param run - The docker seam.
+ * @returns True when `docker info` succeeds.
+ *
+ * @example
+ * ```ts
+ * await docker_isAvailable(); // false on a host without docker
+ * ```
+ */
+export declare function docker_isAvailable(run?: DockerRun): Promise<boolean>;
+/**
+ * Makes sure an image is present locally, pulling it when it is not.
+ *
+ * @param image - The image reference.
+ * @param run - The docker seam.
+ * @returns Null when the image is present; else why it could not be had.
+ *
+ * @example
+ * ```ts
+ * await dockerImage_ensure('fnndsc/pl-dircopy:2.1.1'); // null
+ * ```
+ */
+export declare function dockerImage_ensure(image: string, run?: DockerRun): Promise<string | null>;
+/**
+ * Reads a plugin's descriptor out of its image.
+ *
+ * @param image - The image reference.
+ * @param publicRepo - The plugin's repository, passed to `chris_plugin_info` when known.
+ * @param run - The docker seam.
+ * @returns The descriptor, or null when none of the three ways printed one.
+ *
+ * @example
+ * ```ts
+ * const descriptor: Record<string, unknown> | null = await descriptorFromImage_extract('fnndsc/pl-dircopy:2.1.1');
+ * ```
+ */
+export declare function descriptorFromImage_extract(image: string, publicRepo?: string, run?: DockerRun): Promise<Record<string, unknown> | null>;

package/dist/plugins/plugin_docker.js

@@ -0,0 +1,158 @@
+"use strict";
+/**
+ * @file Reading a plugin's descriptor out of its container image.
+ *
+ * The last way `plugin add` finds a descriptor: pull the image (or use the
+ * local copy) and ask it, trying the three ways ChRIS plugins have printed
+ * one over the years, in chrisomatic's order — `chris_plugin_info` with the
+ * image named, `chris_plugin_info` bare, and the old chrisapp `<CMD> --json`.
+ *
+ * Every docker call is an argument vector run without a shell: an image
+ * reference is operator input and never reaches a command line as text.
+ *
+ * Key components:
+ * - DockerRun: the seam that runs one docker command (tests stub it).
+ * - docker_isAvailable: whether a docker daemon answers.
+ * - dockerImage_ensure: the image locally, pulled when absent.
+ * - descriptorFromImage_extract: the image's descriptor JSON, by the three ways.
+ *
+ * Typical usage:
+ * ```ts
+ * if (await docker_isAvailable() && await dockerImage_ensure(image)) {
+ *   const descriptor: Record<string, unknown> | null = await descriptorFromImage_extract(image);
+ * }
+ * ```
+ *
+ * Dependencies: Node.js `child_process`; a `docker` CLI on the host.
+ *
+ * @module
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.docker_run = void 0;
+exports.docker_isAvailable = docker_isAvailable;
+exports.dockerImage_ensure = dockerImage_ensure;
+exports.descriptorFromImage_extract = descriptorFromImage_extract;
+const node_child_process_1 = require("node:child_process");
+/** Longest a descriptor print may take: some images (TensorFlow, MINC) take minutes. */
+const DESCRIPTOR_TIMEOUT_MS = 10 * 60 * 1000;
+/** Largest output read from a docker command. */
+const OUTPUT_MAX_BYTES = 32 * 1024 * 1024;
+/**
+ * Runs `docker` with an argument vector, no shell.
+ *
+ * @param args - The arguments after `docker`.
+ * @returns What it answered; never throws.
+ *
+ * @example
+ * ```ts
+ * const answer: DockerAnswer = await docker_run(['image', 'inspect', 'alpine']);
+ * ```
+ */
+const docker_run = (args) => new Promise((resolve) => {
+    (0, node_child_process_1.execFile)('docker', [...args], { timeout: DESCRIPTOR_TIMEOUT_MS, maxBuffer: OUTPUT_MAX_BYTES }, (error, stdout, stderr) => {
+        resolve({ ok: error === null, stdout: String(stdout).trim(), stderr: String(stderr || error?.message || '').trim() });
+    });
+});
+exports.docker_run = docker_run;
+/**
+ * Reports whether a docker daemon answers.
+ *
+ * @param run - The docker seam.
+ * @returns True when `docker info` succeeds.
+ *
+ * @example
+ * ```ts
+ * await docker_isAvailable(); // false on a host without docker
+ * ```
+ */
+async function docker_isAvailable(run = exports.docker_run) {
+    return (await run(['info', '--format', '{{.ServerVersion}}'])).ok;
+}
+/**
+ * Makes sure an image is present locally, pulling it when it is not.
+ *
+ * @param image - The image reference.
+ * @param run - The docker seam.
+ * @returns Null when the image is present; else why it could not be had.
+ *
+ * @example
+ * ```ts
+ * await dockerImage_ensure('fnndsc/pl-dircopy:2.1.1'); // null
+ * ```
+ */
+async function dockerImage_ensure(image, run = exports.docker_run) {
+    if ((await run(['image', 'inspect', '--format', '{{.Id}}', image])).ok)
+        return null;
+    const pulled = await run(['pull', '--quiet', image]);
+    return pulled.ok ? null : `docker pull ${image} failed: ${pulled.stderr || 'no reason given'}`;
+}
+/**
+ * Reads a plugin's descriptor out of its image.
+ *
+ * @param image - The image reference.
+ * @param publicRepo - The plugin's repository, passed to `chris_plugin_info` when known.
+ * @param run - The docker seam.
+ * @returns The descriptor, or null when none of the three ways printed one.
+ *
+ * @example
+ * ```ts
+ * const descriptor: Record<string, unknown> | null = await descriptorFromImage_extract('fnndsc/pl-dircopy:2.1.1');
+ * ```
+ */
+async function descriptorFromImage_extract(image, publicRepo, run = exports.docker_run) {
+    const withArgs = ['run', '--rm', image, 'chris_plugin_info', '--dock-image', image];
+    if (publicRepo !== undefined)
+        withArgs.push('--public-repo', publicRepo);
+    const attempts = [
+        () => run(withArgs),
+        () => run(['run', '--rm', image, 'chris_plugin_info']),
+        async () => {
+            const command = await imageCommand_get(image, run);
+            return command === null ? null : run(['run', '--rm', image, command, '--json']);
+        },
+    ];
+    for (const attempt of attempts) {
+        const answer = await attempt();
+        if (answer === null || !answer.ok || answer.stdout === '')
+            continue;
+        const parsed = descriptorJson_parse(answer.stdout);
+        if (parsed !== null)
+            return parsed;
+    }
+    return null;
+}
+/**
+ * Reads an image's default command, for the old chrisapp `--json` way.
+ *
+ * @param image - The image reference.
+ * @param run - The docker seam.
+ * @returns The first word of the image's CMD, or null when it has none.
+ */
+async function imageCommand_get(image, run) {
+    const answer = await run(['image', 'inspect', '--format', '{{json .Config.Cmd}}', image]);
+    if (!answer.ok)
+        return null;
+    try {
+        const command = JSON.parse(answer.stdout);
+        return Array.isArray(command) && typeof command[0] === 'string' ? command[0] : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Parses a printed descriptor.
+ *
+ * @param text - What the image printed.
+ * @returns The descriptor object, or null when the text is not one.
+ */
+function descriptorJson_parse(text) {
+    try {
+        const parsed = JSON.parse(text);
+        return parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=plugin_docker.js.map

package/dist/plugins/plugin_docker.js.map

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

package/dist/plugins/plugin_index.d.ts

@@ -0,0 +1,157 @@
+/**
+ * @file Plugin indexes: where descriptors come from, and reading them.
+ *
+ * A plugin index is a set of plugin descriptors, one JSON file per plugin at
+ * its latest version, in the form CUBE's administrative upload takes, with
+ * the JSON Schema they follow beside them. FNNDSC/chris-plugins is the one
+ * that matters; a directory of `.json` files or a `.tar.gz` holding one is
+ * an index too, on CUBE (how a surface with no host access syncs) or on the
+ * host.
+ *
+ * Every source reads to the same {@link PluginIndex}: its descriptors as
+ * text (so a later check can quote the file), the schema when one came with
+ * them, and the commit when the source can name one. GitHub's archive of a
+ * ref is fetched once, whole; its pax global header names the exact commit.
+ *
+ * Layout read from any source: descriptors are the `.json` files at the root
+ * or under `plugins/`; the schema is `schema/plugin.schema.json` at the root
+ * or one level up (a `plugins/` directory handed over on its own).
+ *
+ * Key components:
+ * - PluginIndexSource: a parsed source (GitHub repository at a ref, CUBE path, host path).
+ * - PluginIndex: the descriptors, schema and commit read from a source.
+ * - pluginIndexSource_parse: read a source word (`FNNDSC/chris-plugins@main`, `host:./plugins`).
+ * - pluginIndexArchive_read: read an index from archive bytes.
+ * - pluginIndex_load: read an index from any source.
+ *
+ * Typical usage:
+ * ```ts
+ * const source: PluginIndexSource | null = pluginIndexSource_parse('FNNDSC/chris-plugins@main', 'cube');
+ * const loaded: Result<PluginIndex> = source ? await pluginIndex_load(source) : Err();
+ * ```
+ *
+ * Dependencies: Node.js built-ins (`node:fs`, `node:path`), `fetch` for the
+ * GitHub archive, salsa's CUBE file reads for CUBE paths.
+ *
+ * @module
+ */
+import { type Result } from '@fnndsc/cumin';
+/**
+ * Where an index is read from.
+ *
+ * @example
+ * ```ts
+ * const source: PluginIndexSource = { kind: 'github', owner: 'FNNDSC', repo: 'chris-plugins', ref: 'main' };
+ * ```
+ */
+export type PluginIndexSource = {
+    readonly kind: 'github';
+    readonly owner: string;
+    readonly repo: string;
+    readonly ref: string;
+} | {
+    readonly kind: 'cube';
+    readonly path: string;
+} | {
+    readonly kind: 'host';
+    readonly path: string;
+};
+/**
+ * One descriptor file of an index.
+ *
+ * @example
+ * ```ts
+ * const descriptor: IndexDescriptor = { file: 'pl-dircopy.json', text: '{"name":"pl-dircopy"}' };
+ * ```
+ */
+export interface IndexDescriptor {
+    /** The file's name (`pl-dircopy.json`), which rule 3 holds to the plugin's name. */
+    readonly file: string;
+    /** The file's text, as read. */
+    readonly text: string;
+}
+/**
+ * An index, read.
+ *
+ * @example
+ * ```ts
+ * const index: PluginIndex = pluginIndexArchive_read(bytes, 'FNNDSC/chris-plugins@main');
+ * index.descriptors.length;
+ * ```
+ */
+export interface PluginIndex {
+    /** The source as the operator would write it. */
+    readonly source: string;
+    /** A short name for headers: `chris-plugins @ 8c9a1f6`. */
+    readonly label: string;
+    /** The full commit the descriptors were read at, when the source names one. */
+    readonly commit: string | null;
+    /** Every descriptor, sorted by file name. */
+    readonly descriptors: IndexDescriptor[];
+    /** The parsed JSON Schema, or null when none came with the descriptors. */
+    readonly schema: unknown;
+}
+/**
+ * Parses an index source word.
+ *
+ * `owner/repo[@ref]` is a GitHub repository; `host:<path>` a host path;
+ * `cube:<path>` a CUBE path. Any other word is a path, read where `bare`
+ * says: `plugin sync` reads a bare path on CUBE, `plugin validate` (which
+ * needs no CUBE) on the host.
+ *
+ * @param word - The source as typed.
+ * @param bare - Where a path with no prefix is read.
+ * @param ref - A ref overriding the word's own (`--ref`), for a GitHub source.
+ * @returns The parsed source, or null for an empty word.
+ *
+ * @example
+ * ```ts
+ * pluginIndexSource_parse('FNNDSC/chris-plugins@v1', 'cube'); // { kind: 'github', …, ref: 'v1' }
+ * pluginIndexSource_parse('host:./plugins', 'cube');          // { kind: 'host', path: './plugins' }
+ * ```
+ */
+export declare function pluginIndexSource_parse(word: string, bare: 'cube' | 'host', ref?: string): PluginIndexSource | null;
+/**
+ * Renders a source as the operator would write it.
+ *
+ * @param source - The parsed source.
+ * @returns The source word (`FNNDSC/chris-plugins@main`, `host:./plugins`, `cube:/home/u/plugins`).
+ *
+ * @example
+ * ```ts
+ * pluginIndexSource_format({ kind: 'host', path: './plugins' }); // 'host:./plugins'
+ * ```
+ */
+export declare function pluginIndexSource_format(source: PluginIndexSource): string;
+/**
+ * Reads an index from archive bytes.
+ *
+ * A single top folder (GitHub's `FNNDSC-chris-plugins-<sha>/`) is the root;
+ * the pax global header's `comment` is the commit.
+ *
+ * @param bytes - The archive, gzipped or plain.
+ * @param source - The source word, for the index's `source` and `label`.
+ * @returns The index.
+ * @throws {Error} When the archive is unreadable, an entry's path is unsafe,
+ *   or the schema it carries is not JSON.
+ *
+ * @example
+ * ```ts
+ * const index: PluginIndex = pluginIndexArchive_read(readFileSync('index.tar.gz'), 'FNNDSC/chris-plugins@main');
+ * ```
+ */
+export declare function pluginIndexArchive_read(bytes: Buffer, source: string): PluginIndex;
+/**
+ * Reads an index from its source.
+ *
+ * @param source - The parsed source.
+ * @param fetcher - The fetch used for GitHub; the global one by default.
+ * @returns The index, or an error on the error stack (the fetch failed, the
+ *   path is not there, the archive is unreadable).
+ *
+ * @example
+ * ```ts
+ * const loaded: Result<PluginIndex> = await pluginIndex_load({ kind: 'host', path: './plugins' });
+ * ```
+ */
+export declare function pluginIndex_load(source: PluginIndexSource, fetcher?: typeof fetch): Promise<Result<PluginIndex>>;