@fnndsc/salsa 4.4.3 → 4.5.0

package/dist/plugins/plugin_index.js

@@ -0,0 +1,338 @@
+"use strict";
+/**
+ * @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
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pluginIndexSource_parse = pluginIndexSource_parse;
+exports.pluginIndexSource_format = pluginIndexSource_format;
+exports.pluginIndexArchive_read = pluginIndexArchive_read;
+exports.pluginIndex_load = pluginIndex_load;
+const node_fs_1 = require("node:fs");
+const nodePath = __importStar(require("node:path"));
+const cumin_1 = require("@fnndsc/cumin");
+const index_js_1 = require("../files/index.js");
+const tar_read_js_1 = require("./tar_read.js");
+/** Where GitHub serves a repository's archive of a ref. */
+const GITHUB_TARBALL_URL = 'https://api.github.com/repos';
+/** The ref read when a GitHub source names none. */
+const DEFAULT_REF = 'main';
+/** File name of the index's JSON Schema. */
+const SCHEMA_FILE = 'plugin.schema.json';
+/** Archive extensions read as a single archive rather than a directory. */
+const ARCHIVE_PATTERN = /\.(tar\.gz|tgz|tar)$/i;
+/** A GitHub repository word: `owner/repo`, optionally `@ref`. */
+const GITHUB_PATTERN = /^([A-Za-z0-9_.-]+)\/([A-Za-z0-9_.-]+)(?:@(\S+))?$/;
+/**
+ * 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' }
+ * ```
+ */
+function pluginIndexSource_parse(word, bare, ref) {
+    const trimmed = word.trim();
+    if (trimmed === '')
+        return null;
+    if (trimmed.startsWith('host:'))
+        return { kind: 'host', path: trimmed.slice('host:'.length) };
+    if (trimmed.startsWith('cube:'))
+        return { kind: 'cube', path: trimmed.slice('cube:'.length) };
+    const github = trimmed.startsWith('.') ? null : GITHUB_PATTERN.exec(trimmed);
+    if (github !== null && github[1] !== undefined && github[2] !== undefined) {
+        return { kind: 'github', owner: github[1], repo: github[2], ref: ref ?? github[3] ?? DEFAULT_REF };
+    }
+    return { kind: bare, path: trimmed };
+}
+/**
+ * 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'
+ * ```
+ */
+function pluginIndexSource_format(source) {
+    if (source.kind === 'github')
+        return `${source.owner}/${source.repo}@${source.ref}`;
+    return `${source.kind}:${source.path}`;
+}
+/**
+ * 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');
+ * ```
+ */
+function pluginIndexArchive_read(bytes, source) {
+    const archive = (0, tar_read_js_1.tarArchive_read)(bytes);
+    const root = archiveRoot_find(archive.files);
+    const entries = archive.files
+        .filter((file) => file.path.startsWith(root))
+        .map((file) => ({ path: file.path.slice(root.length), text: file.content.toString('utf8') }));
+    const commit = archive.globals['comment'] ?? null;
+    return pluginIndex_assemble(source, commit, entries);
+}
+/**
+ * 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' });
+ * ```
+ */
+async function pluginIndex_load(source, fetcher = fetch) {
+    const word = pluginIndexSource_format(source);
+    try {
+        if (source.kind === 'github')
+            return (0, cumin_1.Ok)(await pluginIndexGitHub_fetch(source, fetcher));
+        if (source.kind === 'host')
+            return (0, cumin_1.Ok)(await pluginIndexHost_read(source.path, word));
+        return await pluginIndexCube_read(source.path, word);
+    }
+    catch (error) {
+        cumin_1.errorStack.stack_push('error', `plugin index ${word}: ${error instanceof Error ? error.message : String(error)}`);
+        return (0, cumin_1.Err)();
+    }
+}
+/**
+ * Fetches a GitHub repository's archive of a ref and reads it.
+ *
+ * @param source - The GitHub source.
+ * @param fetcher - The fetch to use.
+ * @returns The index.
+ * @throws {Error} When GitHub does not answer with the archive.
+ */
+async function pluginIndexGitHub_fetch(source, fetcher) {
+    const url = `${GITHUB_TARBALL_URL}/${source.owner}/${source.repo}/tarball/${encodeURIComponent(source.ref)}`;
+    const response = await fetcher(url, { headers: { Accept: 'application/vnd.github+json' } });
+    if (!response.ok)
+        throw new Error(`GitHub answered HTTP ${response.status} for ${url}`);
+    const bytes = Buffer.from(await response.arrayBuffer());
+    return pluginIndexArchive_read(bytes, `${source.owner}/${source.repo}@${source.ref}`);
+}
+/**
+ * Reads an index from a host path: a directory or an archive.
+ *
+ * @param path - The host path.
+ * @param word - The source word.
+ * @returns The index.
+ * @throws {Error} When the path cannot be read.
+ */
+async function pluginIndexHost_read(path, word) {
+    if (ARCHIVE_PATTERN.test(path))
+        return pluginIndexArchive_read(await node_fs_1.promises.readFile(path), word);
+    const entries = [];
+    for (const [relative, directory] of [['', path], ['plugins/', nodePath.join(path, 'plugins')]]) {
+        const names = await directoryNames_read(directory);
+        for (const name of names.filter((candidate) => candidate.endsWith('.json'))) {
+            entries.push({ path: `${relative}${name}`, text: await node_fs_1.promises.readFile(nodePath.join(directory, name), 'utf8') });
+        }
+    }
+    for (const relative of [`schema/${SCHEMA_FILE}`, `../schema/${SCHEMA_FILE}`]) {
+        const text = await node_fs_1.promises.readFile(nodePath.join(path, relative), 'utf8').catch(() => null);
+        if (text !== null)
+            entries.push({ path: relative, text });
+    }
+    return pluginIndex_assemble(word, null, entries);
+}
+/**
+ * Lists a host directory's file names, or none when it is not there.
+ *
+ * @param directory - The host directory.
+ * @returns Its entries' names; empty when the directory does not exist.
+ * @throws {Error} On a read failure other than absence.
+ */
+async function directoryNames_read(directory) {
+    try {
+        return (await node_fs_1.promises.readdir(directory)).sort();
+    }
+    catch (error) {
+        if (error.code === 'ENOENT' || error.code === 'ENOTDIR')
+            return [];
+        throw error;
+    }
+}
+/**
+ * Reads an index from a CUBE path: a directory or an uploaded archive.
+ *
+ * @param path - The CUBE path, absolute.
+ * @param word - The source word.
+ * @returns The index, or an error on the error stack.
+ */
+async function pluginIndexCube_read(path, word) {
+    if (ARCHIVE_PATTERN.test(path)) {
+        const bytes = await (0, index_js_1.fileContent_getBinary)(path);
+        return bytes.ok ? (0, cumin_1.Ok)(pluginIndexArchive_read(bytes.value, word)) : (0, cumin_1.Err)();
+    }
+    const root = path.replace(/\/+$/, '');
+    const items = await (0, index_js_1.files_listRecursive)(root);
+    const entries = [];
+    for (const item of items.filter((candidate) => candidate.type === 'file')) {
+        const relative = item.path.replace(/^\/+/, '').slice(root.replace(/^\/+/, '').length + 1);
+        if (!/^(plugins\/)?[^/]+\.json$/.test(relative) && relative !== `schema/${SCHEMA_FILE}`)
+            continue;
+        const text = await (0, index_js_1.fileContent_get)(`${root}/${relative}`);
+        if (!text.ok)
+            return (0, cumin_1.Err)();
+        entries.push({ path: relative, text: text.value });
+    }
+    if (!entries.some((entry) => entry.path.endsWith(SCHEMA_FILE))) {
+        const above = await (0, index_js_1.fileContent_get)(`${nodePath.posix.dirname(root)}/schema/${SCHEMA_FILE}`);
+        // An index handed over without its schema is still an index; rule 1
+        // then says it was not checked rather than this read failing.
+        if (above.ok)
+            entries.push({ path: `../schema/${SCHEMA_FILE}`, text: above.value });
+        else
+            cumin_1.errorStack.stack_pop();
+    }
+    return (0, cumin_1.Ok)(pluginIndex_assemble(word, null, entries));
+}
+/**
+ * Finds an archive's single top folder, the index's root.
+ *
+ * @param files - The archive's files.
+ * @returns The root with its trailing slash, or '' when the files share none.
+ */
+function archiveRoot_find(files) {
+    const tops = new Set(files.map((file) => file.path.split('/')[0] ?? ''));
+    const top = [...tops][0];
+    return tops.size === 1 && top !== undefined && files.every((file) => file.path.includes('/')) ? `${top}/` : '';
+}
+/**
+ * Builds an index from its files, by the layout every source shares.
+ *
+ * @param source - The source word.
+ * @param commit - The commit, when the source names one.
+ * @param entries - The files, relative to the root.
+ * @returns The index.
+ * @throws {Error} When the schema file is not JSON.
+ */
+function pluginIndex_assemble(source, commit, entries) {
+    const descriptors = entries
+        .filter((entry) => /^(plugins\/)?[^/]+\.json$/.test(entry.path) && !entry.path.endsWith(SCHEMA_FILE))
+        .map((entry) => ({ file: entry.path.replace(/^plugins\//, ''), text: entry.text }))
+        .sort((a, b) => a.file.localeCompare(b.file));
+    const schemaEntry = entries.find((entry) => entry.path === `schema/${SCHEMA_FILE}`)
+        ?? entries.find((entry) => entry.path === `../schema/${SCHEMA_FILE}`);
+    let schema = null;
+    if (schemaEntry !== undefined) {
+        try {
+            schema = JSON.parse(schemaEntry.text);
+        }
+        catch {
+            throw new Error(`${schemaEntry.path} is not JSON`);
+        }
+    }
+    return { source, label: indexLabel_build(source, commit), commit, descriptors, schema };
+}
+/**
+ * Builds an index's short name for headers.
+ *
+ * @param source - The source word.
+ * @param commit - The commit, when known.
+ * @returns `chris-plugins @ 8c9a1f6` for a repository, else the source word.
+ */
+function indexLabel_build(source, commit) {
+    const github = GITHUB_PATTERN.exec(source);
+    if (github === null || source.includes(':'))
+        return commit === null ? source : `${source} @ ${commit.slice(0, 7)}`;
+    return `${github[2] ?? source} @ ${commit === null ? (github[3] ?? DEFAULT_REF) : commit.slice(0, 7)}`;
+}
+//# sourceMappingURL=plugin_index.js.map

package/dist/plugins/plugin_index.js.map

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

package/dist/plugins/plugin_sync.d.ts

@@ -0,0 +1,276 @@
+/**
+ * @file Filling a CUBE from a plugin index: `plugin sync`.
+ *
+ * A sync is a plan, then the plan's adds. The plan compares every descriptor
+ * in the index with what the connected CUBE holds and puts each plugin in
+ * one group:
+ *
+ * | group | what it means | action |
+ * |---|---|---|
+ * | add | not in the CUBE | add |
+ * | newer | the index has a newer version | add beside the older one |
+ * | skip | same name and version, same descriptor | nothing |
+ * | cubeNewer | the CUBE has a newer version | report |
+ * | drift | same name and version, different descriptor | report, never touched |
+ * | imageTaken | the image is registered under another version | report: CUBE would refuse it |
+ * | cubeOnly | in the CUBE, not in the index | report |
+ * | invalid | fails rules 1–4 of `plugin validate` | report, never uploaded |
+ *
+ * A sync never deletes and never changes a plugin already there: deleting
+ * cascades to its runs and to its nodes in every pipeline, and CUBE's admin
+ * `PUT` changes only compute resources, so a descriptor cannot be corrected
+ * in place anyway. Drift ignores what only reflects CUBE's defaults (a limit
+ * the index leaves out because it equals the default, `1000m` against a
+ * stored `1000`, a field CUBE fills in when it is not given).
+ *
+ * Applying uploads the plan's adds four at a time, each failure contained to
+ * its plugin; what landed stays, so a rerun continues where a stopped one
+ * left off. Every CUBE read and the upload go through {@link SyncSeams}, so
+ * the plan and the apply are testable without a CUBE.
+ *
+ * Key components:
+ * - SyncGroup / SyncPlanEntry / SyncPlan: the plan.
+ * - SyncResult / SyncReceipt: what applying it did.
+ * - SyncSeams / syncSeams_cube: the CUBE reads and the upload.
+ * - syncPlan_build: compare an index with the CUBE.
+ * - syncPlanAdds_list: the entries a plan would upload.
+ * - syncPlan_apply: upload them, four at a time.
+ * - descriptorDrift_find: how two descriptors of one version differ, defaults aside.
+ * - version_compare: dotted-number ordering.
+ *
+ * Typical usage:
+ * ```ts
+ * const plan: SyncPlan = await syncPlan_build(index, ['host'], syncSeams_cube);
+ * const receipt: SyncReceipt = await syncPlan_apply(plan, syncSeams_cube, (r: SyncResult): void => console.log(r));
+ * ```
+ *
+ * Dependencies: cumin's CUBE reads (plugin pages, parameters) and the
+ * administrative upload; the index and its local checks.
+ *
+ * @module
+ */
+import type { PluginIndex } from './plugin_index.js';
+/** The groups a plan's entries fall in, in the order a plan lists them. */
+export declare const SYNC_GROUPS: readonly ["add", "newer", "skip", "cubeNewer", "drift", "imageTaken", "cubeOnly", "invalid"];
+/** One group of the plan. */
+export type SyncGroup = typeof SYNC_GROUPS[number];
+/** The groups that upload. */
+export declare const SYNC_ADD_GROUPS: readonly SyncGroup[];
+/**
+ * One plugin's place in the plan.
+ *
+ * @example
+ * ```ts
+ * const entry: SyncPlanEntry = { group: 'newer', name: 'pl-x', version: '1.2.0', cubeVersions: ['1.1.0'] };
+ * ```
+ */
+export interface SyncPlanEntry {
+    /** Its group. */
+    readonly group: SyncGroup;
+    /** The plugin's name (the file's, for an invalid descriptor that names none). */
+    readonly name: string;
+    /** The index's version, when the entry comes from the index. */
+    readonly version?: string;
+    /** The versions the CUBE holds of this name. */
+    readonly cubeVersions?: string[];
+    /** The index file it comes from. */
+    readonly file?: string;
+    /** Why it is in a report group, in a line. */
+    readonly detail?: string;
+    /** The descriptor's text, for the entries that upload. */
+    readonly descriptor?: string;
+}
+/**
+ * The plan.
+ *
+ * @example
+ * ```ts
+ * const plan: SyncPlan = await syncPlan_build(index, ['host'], seams);
+ * plan.entries.filter((e: SyncPlanEntry): boolean => e.group === 'add').length;
+ * ```
+ */
+export interface SyncPlan {
+    /** The index's short name (`chris-plugins @ 8c9a1f6`). */
+    readonly label: string;
+    /** The index's source word. */
+    readonly source: string;
+    /** The commit read, when known. */
+    readonly commit: string | null;
+    /** How many descriptors the index holds. */
+    readonly indexed: number;
+    /** The compute resources adds are registered on. */
+    readonly computes: string[];
+    /** Every entry, by group then name. */
+    readonly entries: SyncPlanEntry[];
+}
+/**
+ * One upload's outcome.
+ *
+ * @example
+ * ```ts
+ * const result: SyncResult = { name: 'pl-x', version: '1.2.0', ok: false, reason: 'Plugin with name pl-x and version 1.2.0 already exists.' };
+ * ```
+ */
+export interface SyncResult {
+    /** The plugin. */
+    readonly name: string;
+    /** Its version. */
+    readonly version: string;
+    /** True when CUBE registered it. */
+    readonly ok: boolean;
+    /** CUBE's reason, when it refused. */
+    readonly reason?: string;
+}
+/**
+ * What applying a plan did.
+ *
+ * @example
+ * ```ts
+ * const receipt: SyncReceipt = await syncPlan_apply(plan, seams, () => undefined);
+ * receipt.failed === 0;
+ * ```
+ */
+export interface SyncReceipt {
+    /** The plan applied. */
+    readonly plan: SyncPlan;
+    /** Each upload's outcome, in plan order. */
+    readonly results: SyncResult[];
+    /** Plugins registered. */
+    readonly added: number;
+    /** Plugins already there, the same. */
+    readonly skipped: number;
+    /** Plugins in a report group. */
+    readonly reported: number;
+    /** Uploads that should have worked and did not. */
+    readonly failed: number;
+    /** Whether a stop (`kill %N`, Ctrl-C) ended it before every add was sent. */
+    readonly stopped: boolean;
+    /** Adds the plan had that were never sent, because it was stopped. */
+    readonly unsent: number;
+}
+/**
+ * One plugin row the CUBE holds.
+ *
+ * @example
+ * ```ts
+ * const row: CubePluginRow = { name: 'pl-x', version: '1.0.0', dock_image: 'fnndsc/pl-x:1.0.0' };
+ * ```
+ */
+export interface CubePluginRow {
+    /** Its name. */
+    readonly name: string;
+    /** Its version. */
+    readonly version: string;
+    /** Its image. */
+    readonly dock_image: string;
+}
+/** What an upload answered. */
+export type UploadAnswer = {
+    readonly ok: true;
+} | {
+    readonly ok: false;
+    readonly reason: string;
+};
+/**
+ * The CUBE reads and the upload a sync needs.
+ *
+ * @example
+ * ```ts
+ * const seams: SyncSeams = { ...syncSeams_cube, descriptor_upload: async () => ({ ok: true }) };
+ * ```
+ */
+export interface SyncSeams {
+    /**
+     * Reads every plugin the CUBE holds.
+     *
+     * @returns The rows, every page.
+     */
+    cubePlugins_read(): Promise<CubePluginRow[]>;
+    /**
+     * Reads one registered version whole: its fields and every parameter.
+     *
+     * @param name - The plugin's name.
+     * @param version - The version.
+     * @returns The plugin's fields with `parameters`, or null when CUBE has no such version.
+     */
+    cubeDescriptor_read(name: string, version: string): Promise<Record<string, unknown> | null>;
+    /**
+     * Uploads one descriptor.
+     *
+     * @param descriptor - The descriptor's text.
+     * @param computes - Compute resources to register it on.
+     * @returns Whether CUBE registered it, and why not.
+     */
+    descriptor_upload(descriptor: string, computes: string[]): Promise<UploadAnswer>;
+}
+/** The connected CUBE's reads and upload. */
+export declare const syncSeams_cube: SyncSeams;
+/**
+ * Builds the plan: compares an index with the connected CUBE.
+ *
+ * @param index - The index.
+ * @param computes - The compute resources adds would be registered on.
+ * @param seams - The CUBE reads.
+ * @returns The plan.
+ * @throws {Error} When the CUBE cannot be read.
+ *
+ * @example
+ * ```ts
+ * const plan: SyncPlan = await syncPlan_build(index, ['host'], syncSeams_cube);
+ * ```
+ */
+export declare function syncPlan_build(index: PluginIndex, computes: string[], seams: SyncSeams): Promise<SyncPlan>;
+/**
+ * Lists the entries a plan would upload.
+ *
+ * @param plan - The plan.
+ * @returns Its add and newer entries, in plan order.
+ *
+ * @example
+ * ```ts
+ * syncPlanAdds_list(plan).length; // how many plugins a yes registers
+ * ```
+ */
+export declare function syncPlanAdds_list(plan: SyncPlan): SyncPlanEntry[];
+/**
+ * Applies a plan: uploads its adds, four at a time.
+ *
+ * @param plan - The plan.
+ * @param seams - The upload.
+ * @param note - Called once per upload as it lands, in the order they land.
+ * @param signal - A stop: the uploads in flight finish, no more start, and
+ *   what landed stays (a rerun continues from it).
+ * @returns What it did, `stopped` when the signal ended it early.
+ *
+ * @example
+ * ```ts
+ * const receipt: SyncReceipt = await syncPlan_apply(plan, syncSeams_cube, (r: SyncResult): void => console.log(r.name, r.ok));
+ * ```
+ */
+export declare function syncPlan_apply(plan: SyncPlan, seams: SyncSeams, note: (result: SyncResult) => void, signal?: AbortSignal): Promise<SyncReceipt>;
+/**
+ * Finds how two descriptors of one version differ, CUBE's defaults aside.
+ *
+ * @param indexed - The index's descriptor.
+ * @param held - The CUBE's plugin fields with its `parameters`.
+ * @returns The differing fields (`dock_image`, `parameters.--dir.help`), empty when none.
+ *
+ * @example
+ * ```ts
+ * descriptorDrift_find({ min_cpu_limit: '1000m' }, { min_cpu_limit: 1000 }); // []
+ * ```
+ */
+export declare function descriptorDrift_find(indexed: Record<string, unknown>, held: Record<string, unknown>): string[];
+/**
+ * Orders two dotted-number versions.
+ *
+ * @param a - One version.
+ * @param b - The other.
+ * @returns Negative when `a` is older, positive when newer, zero when equal.
+ *
+ * @example
+ * ```ts
+ * ['1.10.0', '1.2.0'].sort(version_compare); // ['1.2.0', '1.10.0']
+ * ```
+ */
+export declare function version_compare(a: string, b: string): number;