@fnndsc/brasa 0.34.0 → 0.35.1

package/dist/chris/completion.js

@@ -0,0 +1,100 @@
+/**
+ * @file What a ChRIS session adds to completion: its plugins as command
+ * words, a pipeline's `--node.field` options, and the names completed at `/`.
+ *
+ * @module
+ */
+import { plugins_listAll, pipelineManifest_get } from '@fnndsc/salsa';
+import { listCache_get } from '@fnndsc/cumin';
+/**
+ * Fetches available plugin names from /bin in the format: name-vVersion.
+ * This matches the display format used in /bin listings.
+ * Uses cache first for fast completion.
+ * @returns Array of plugin names with version suffixes.
+ */
+async function plugins_getNames() {
+    try {
+        // Check cache first for /bin
+        const listCache = listCache_get();
+        const cached = listCache.cache_get('/bin');
+        if (cached && cached.data) {
+            // Return cached plugin names immediately
+            return cached.data.map((item) => item.name);
+        }
+        // Cache miss - fetch from API (only on first tab completion)
+        const plugins = await plugins_listAll({});
+        if (plugins && plugins.tableData) {
+            const pluginNames = plugins.tableData.map((p) => {
+                const name = typeof p.name === 'string' ? p.name : String(p.name ?? '');
+                const version = typeof p.version === 'string' ? p.version : String(p.version ?? '');
+                // Format as name-vVersion to match /bin display format
+                return version ? `${name}-v${version}` : name;
+            });
+            // Cache it for next time
+            const lsItems = plugins.tableData.map((p) => {
+                const name = typeof p.name === 'string' ? p.name : String(p.name ?? '');
+                const version = typeof p.version === 'string' ? p.version : String(p.version ?? '');
+                return {
+                    name: version ? `${name}-v${version}` : name,
+                    type: 'plugin',
+                    size: 0,
+                    owner: 'system',
+                    date: p.creation_date ? String(p.creation_date) : '',
+                };
+            });
+            listCache.cache_set('/bin', lsItems);
+            return pluginNames;
+        }
+    }
+    catch (e) {
+        // Silently fail if plugins cannot be fetched
+    }
+    return [];
+}
+/** The fields every pipeline node takes for its execution. */
+const EXECUTION_FIELDS = [
+    'compute_resource_name', 'cpu_limit', 'memory_limit', 'gpu_limit', 'number_of_workers',
+];
+/**
+ * The `--node.field` options of the pipeline a line runs (`pipeline run X`
+ * or `X` itself), starting with the word typed.
+ *
+ * @param args - The line's words.
+ * @param word - The option word typed so far.
+ * @returns The options, none when the pipeline cannot be read, or null for
+ *   a line naming no pipeline.
+ */
+async function pipelineOptions_get(args, word) {
+    const pipelineSpecifier = args[0] === 'pipeline' && args[1] === 'run'
+        ? args[2]
+        : args[0];
+    if (pipelineSpecifier === undefined)
+        return null;
+    const result = await pipelineManifest_get(pipelineSpecifier);
+    if (!result.ok)
+        return [];
+    const options = [];
+    const manifest = result.value;
+    for (const node of manifest.nodes) {
+        const titleUsable = /^[A-Za-z0-9_-]+$/.test(node.title) &&
+            manifest.nodes.filter((candidate) => candidate.title === node.title).length === 1;
+        const selectors = titleUsable ? [node.title, `@${node.pipingID}`] : [`@${node.pipingID}`];
+        const fields = [
+            ...EXECUTION_FIELDS,
+            ...(node.parameterDefinitions ?? [])
+                .filter((parameter) => parameter.name !== 'plugininstances')
+                .map((parameter) => parameter.name),
+        ];
+        for (const field of fields) {
+            options.push(...selectors.map((selector) => `--${selector}.${field}`));
+        }
+    }
+    return options.filter((option) => option.startsWith(word));
+}
+/** What the ChRIS session adds to completion. */
+export const chrisCompletion = {
+    commandWords: plugins_getNames,
+    options: pipelineOptions_get,
+    rootWords: ['bin', 'usr'],
+};
+//# sourceMappingURL=completion.js.map

package/dist/chris/completion.js.map

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

package/dist/chris/connect.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"connect.js","sourceRoot":"","sources":["../../src/chris/connect.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAC9C,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAClD,OAAO,EAAyB,YAAY,EAAE,OAAO,EAA4B,MAAM,eAAe,CAAC;AAqBvG;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,wBAAwB;IAC5C,MAAM,OAAO,GAAkB,MAAM,iBAAiB,EAAE,CAAC;IAEzD,IAAI,CAAC,OAAO,CAAC,IAAI,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC;QAClC,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,OAAO,EAAE,CAAC;IAC3C,CAAC;IAED,MAAM,KAAK,GAAkB,MAAM,OAAO,CAAC,UAAU,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC;IAC1E,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC;QACvB,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,OAAO,EAAE,CAAC;IACzC,CAAC;IAED,IAAI,CAAC;QACH,MAAM,MAAM,GAAkB,MAAM,OAAO,CAAC,UAAU,CAAC,UAAU,EAAE,CAAC;QACpE,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC;YACvB,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,OAAO,EAAE,CAAC;QAC1C,CAAC;QACD,MAAM,MAAM,CAAC,OAAO,EAAE,CAAC;QACvB,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,OAAO,EAAE,CAAC;IACzC,CAAC;IAAC,OAAO,KAAc,EAAE,CAAC;QACxB,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC;QACvB,OAAO,EAAE,MAAM,EAAE,eAAe,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;IAC7G,CAAC;AACH,CAAC;AAeD;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,KAAK,UAAU,wBAAwB,CAAC,IAAY,EAAE,GAAW,EAAE,KAAa;IACrF,MAAM,OAAO,GAAwB,MAAM,OAAO,CAAC,UAAU,CAAC,2BAA2B,CAAC,EAAE,IAAI,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC,CAAC;IAChH,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,CAAC;QACvB,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC;QACvB,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,iBAAiB,EAAE,EAAE,KAAK,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC;IAC1F,CAAC;IACD,OAAO,CAAC,OAAO,GAAG,KAAK,CAAC;IACxB,MAAM,YAAY,CAAC,WAAW,CAAC,OAAO,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;IACxD,MAAM,YAAY,CAAC,WAAW,CAAC,OAAO,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;IACtD,MAAM,YAAY,CAAC,WAAW,CAAC,OAAO,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC;IACtD,MAAM,YAAY,CAAC,WAAW,CAAC,OAAO,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC;IACxD,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,iBAAiB,EAAE,EAAE,CAAC;AACrE,CAAC"}

package/dist/chris/debug.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @file Debugging in a ChRIS session: the CUBE connection's own flag.
+ *
+ * @module
+ */
+import type { Backend } from '../core/backend.js';
+/** Whether the CUBE connection is debugging, or null until its configuration exists. */
+export declare const chrisDebug_get: NonNullable<Backend['debug_get']>;
+/** Turns the CUBE connection's debugging on or off, once its configuration exists. */
+export declare const chrisDebug_set: NonNullable<Backend['debug_set']>;

package/dist/chris/debug.js

@@ -0,0 +1,9 @@
+import { session } from '../session/index.js';
+/** Whether the CUBE connection is debugging, or null until its configuration exists. */
+export const chrisDebug_get = () => (session.connection?.config ? Boolean(session.connection.config.debug) : null);
+/** Turns the CUBE connection's debugging on or off, once its configuration exists. */
+export const chrisDebug_set = (on) => {
+    if (session.connection?.config)
+        session.connection.config.debug = on;
+};
+//# sourceMappingURL=debug.js.map

package/dist/chris/debug.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"debug.js","sourceRoot":"","sources":["../../src/chris/debug.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAE9C,wFAAwF;AACxF,MAAM,CAAC,MAAM,cAAc,GAAsC,GAAmB,EAAE,CACpF,CAAC,OAAO,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,UAAU,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;AAEjF,sFAAsF;AACtF,MAAM,CAAC,MAAM,cAAc,GAAsC,CAAC,EAAW,EAAQ,EAAE;IACrF,IAAI,OAAO,CAAC,UAAU,EAAE,MAAM;QAAE,OAAO,CAAC,UAAU,CAAC,MAAM,CAAC,KAAK,GAAG,EAAE,CAAC;AACvE,CAAC,CAAC"}

package/dist/chris/files.d.ts

@@ -0,0 +1,16 @@
+import type { Backend } from '../core/backend.js';
+import { FileReadRefusal } from '../core/fileRefusal.js';
+/**
+ * Reads the kernel's notes since a checkpoint and names the refusal: a
+ * status for the route and a line for the operator. CUBE's own status is
+ * taken from the note when it carries one; a file the lookup could not
+ * find is 404; anything else is the kernel's own failure, 502, so a 404
+ * never again stands for "something went wrong".
+ *
+ * @param filePath - The file asked for.
+ * @param notes - The kernel's error notes since the read began, oldest first.
+ * @returns The refusal to throw.
+ */
+export declare function fileRefusal_name(filePath: string, notes: ReadonlyArray<string>): FileReadRefusal;
+/** The ChRIS backend's files. */
+export declare const chrisFiles: NonNullable<Backend['files']>;

package/dist/chris/files.js

@@ -0,0 +1,178 @@
+/**
+ * @file The ChRIS backend's file bytes for a surface: read from and written
+ * to CUBE at a path the session resolves, `/proc` projections included.
+ *
+ * @module
+ */
+import { vfsOutcome_toResult } from '@fnndsc/fond';
+import { FileReadRefusal } from '../core/fileRefusal.js';
+/**
+ * Reads the kernel's notes since a checkpoint and names the refusal: a
+ * status for the route and a line for the operator. CUBE's own status is
+ * taken from the note when it carries one; a file the lookup could not
+ * find is 404; anything else is the kernel's own failure, 502, so a 404
+ * never again stands for "something went wrong".
+ *
+ * @param filePath - The file asked for.
+ * @param notes - The kernel's error notes since the read began, oldest first.
+ * @returns The refusal to throw.
+ */
+export function fileRefusal_name(filePath, notes) {
+    const last = notes[notes.length - 1] ?? '';
+    const status = notes.map((note) => Number(/\b(40[0-9]|41[0-9]|5[0-9][0-9])\b/.exec(note)?.[1] ?? NaN)).find((n) => !Number.isNaN(n));
+    if (status === 403 || status === 401)
+        return new FileReadRefusal(filePath, 403, 'not yours to read: CUBE refused the bytes (403)');
+    if (status === 404 || /not found|no files found/i.test(last))
+        return new FileReadRefusal(filePath, 404, 'no such file in CUBE (404)');
+    if (status !== undefined && status >= 500)
+        return new FileReadRefusal(filePath, 502, `CUBE could not serve it (${status})`);
+    // A note reads `[function     ] | message`; the operator gets the message.
+    return new FileReadRefusal(filePath, 502, last.replace(/^\[[^\]]*\]\s*\|\s*/, '').trim() || 'could not be read');
+}
+/**
+ * Writes bytes to one ChRIS path through the kernel's own create.
+ *
+ * A browser surface holds bytes the daemon's machine has never seen; this
+ * is how they reach the store without any surface talking to CUBE.
+ *
+ * @param filePath - The destination path (absolute or cwd-relative).
+ * @param bytes - The content to write.
+ * @throws {Error} When the store refused the write.
+ */
+async function file_write(filePath, bytes) {
+    const { path_resolve } = await import('../builtins/utils.js');
+    const { files_create } = await import('@fnndsc/salsa');
+    const { listCache_get } = await import('@fnndsc/cumin');
+    const resolved = await path_resolve(filePath);
+    const written = await files_create(bytes, resolved);
+    if (!written) {
+        throw new Error(`cannot write ${filePath}`);
+    }
+    // A write invalidates the listing it changed, as every writing builtin
+    // does. Without this the browser that delivered the file asks for the
+    // folder again and is served the folder as it was before the delivery —
+    // which reads as an upload that silently did nothing.
+    const parent = resolved.replace(/\/[^/]*$/, '') || '/';
+    listCache_get().cache_invalidate(parent);
+}
+/**
+ * A `/proc` job data path as the physical file behind it, when the node's
+ * output folder is a link. Returns the input unchanged when it is not a
+ * data path or resolves no further.
+ *
+ * @param projected - A path under a projection.
+ * @returns The physical path, or the input.
+ */
+async function projectedPath_physical(projected) {
+    try {
+        const link = /^(\/proc\/jobs\/feed_\d+\/[^/]+\/data)(\/.*)?$/.exec(projected);
+        if (link === null)
+            return projected;
+        const { vfsDispatcher } = await import('@fnndsc/salsa');
+        const target = await vfsDispatcher.linkTarget_resolve(link[1]);
+        if (!target.ok)
+            return projected;
+        const { logical_toPhysical } = await import('@fnndsc/chili/utils');
+        const physical = await logical_toPhysical(`${target.value}${link[2] ?? ''}`);
+        return physical.ok ? physical.value : projected;
+    }
+    catch {
+        return projected;
+    }
+}
+/**
+ * Reads one ChRIS file's raw bytes through ChILI, resolved against the
+ * session's working directory.
+ *
+ * Resolved, as its twin {@link file_write} is: a surface addresses a file
+ * the way the session does, and the session's paths include the relative
+ * ones and the `/proc` projections. Handing the raw path to ChILI meant a
+ * volume produced by a run could not be read at the address the graph
+ * itself gives for it — the node's own `data` — while the same bytes read
+ * fine under `/home`. One file, two names, one of them refused.
+ *
+ * @param filePath - The file's path (absolute, cwd-relative, or projected).
+ * @returns The file's bytes.
+ * @throws {Error} When the path does not resolve to a readable file.
+ */
+async function file_read(filePath) {
+    const { path_resolve } = await import('../builtins/utils.js');
+    const { errorStack } = await import('@fnndsc/fond');
+    const since = errorStack.checkpoint_mark();
+    const refusal = () => fileRefusal_name(filePath, errorStack.checkpoint_drain(since).map((note) => note.message));
+    const resolved = await path_resolve(filePath);
+    const { vfsDispatcher } = await import('@fnndsc/salsa');
+    // A projection is read by the provider that owns it — `/proc/jobs/…/data`
+    // follows the node's own data link and delegates to the file behind it.
+    // ChILI's cat knows only CFS, so a path under a projection reached this
+    // route and 404'd: the volume a run had just produced could not be read
+    // at the address its own graph gives for it.
+    if (vfsDispatcher.path_isVirtual(resolved)) {
+        const projected = vfsOutcome_toResult(await vfsDispatcher.readBinary(resolved), 'readBinary', resolved);
+        if (projected.ok)
+            return projected.value;
+        // A node's data link can point at a folder that is ITSELF a link — a
+        // `pl-dircopy` of a PACS pull stores its DICOM under `/SERVICES/PACS`
+        // — and the provider hands back the logical name, which no file id
+        // answers to. Follow it the rest of the way rather than refusing a
+        // file the same graph just listed.
+        const physical = await projectedPath_physical(resolved);
+        if (physical !== resolved) {
+            const { files_catBinary: catLinked } = await import('@fnndsc/chili/commands/fs/cat.js');
+            const followed = await catLinked(physical);
+            if (followed.ok)
+                return followed.value;
+        }
+        throw refusal();
+    }
+    const { files_catBinary } = await import('@fnndsc/chili/commands/fs/cat.js');
+    const result = await files_catBinary(resolved);
+    if (!result.ok) {
+        throw refusal();
+    }
+    errorStack.checkpoint_drain(since);
+    return result.value;
+}
+/**
+ * Opens one ChRIS file's bytes as a stream, resolved as {@link file_read}
+ * resolves, so a download is served as CUBE sends it and never held whole
+ * in the daemon. A projection (`/proc/…/data`) is read whole, as before:
+ * those are small virtual files or links the read already follows.
+ *
+ * @param filePath - The file's path (absolute, cwd-relative, or projected).
+ * @returns The stream and its size when CUBE gave one.
+ * @throws {FileReadRefusal} When the file cannot be opened, with the kernel's reason.
+ */
+async function file_stream(filePath) {
+    const { path_resolve } = await import('../builtins/utils.js');
+    const { vfsDispatcher, fileContent_getBinaryStream } = await import('@fnndsc/salsa');
+    const resolved = await path_resolve(filePath);
+    // A node's `/proc/…/data` path streams the file behind its data link; any
+    // other projection is small and read whole.
+    let target = resolved;
+    if (vfsDispatcher.path_isVirtual(resolved)) {
+        target = await projectedPath_physical(resolved);
+        if (target === resolved) {
+            const bytes = await file_read(filePath);
+            const { Readable } = await import('node:stream');
+            return { stream: Readable.from(bytes), size: bytes.length };
+        }
+    }
+    const { errorStack } = await import('@fnndsc/fond');
+    const since = errorStack.checkpoint_mark();
+    const { path_resolveChrisFs } = await import('@fnndsc/chili/utils/cli.js');
+    const physical = await path_resolveChrisFs(target, {});
+    const opened = await fileContent_getBinaryStream(physical);
+    const notes = errorStack.checkpoint_drain(since).map((note) => note.message);
+    if (!opened.ok)
+        throw fileRefusal_name(filePath, notes);
+    const value = opened.value;
+    return { stream: value.stream, ...(value.size !== undefined ? { size: value.size } : {}) };
+}
+/** The ChRIS backend's files. */
+export const chrisFiles = {
+    read: file_read,
+    write: file_write,
+    stream: file_stream,
+};
+//# sourceMappingURL=files.js.map

package/dist/chris/files.js.map

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

package/dist/chris/filesystem.d.ts

@@ -0,0 +1,3 @@
+import type { BackendFilesystem } from '../core/backend.js';
+/** The ChRIS session's filesystem. */
+export declare const chrisFilesystem: BackendFilesystem;

package/dist/chris/filesystem.js

@@ -0,0 +1,57 @@
+/**
+ * @file The filesystem of a ChRIS session, as the core's listings read it:
+ * salsa's dispatcher (CUBE's mounts, and `/bin` from `mounts.ts`), cumin's
+ * listing cache, a feed's tags, and the link-aware path walk.
+ *
+ * @module
+ */
+import { vfsDispatcher } from '@fnndsc/salsa';
+import { listCache_get, feedTags_byFeed } from '@fnndsc/cumin';
+import { errorStack } from '@fnndsc/fond';
+import { CHRIS_STRUCTURAL_PATHS, chrisFolder_enter, chrisSegment_title } from './navigation.js';
+/**
+ * Hangs each feed's tags on its row, for a long listing that holds feeds
+ * (`feed_N` rows). A listing with no feed in it reads nothing; a map that
+ * cannot be read leaves the rows as they were.
+ *
+ * @param items - The rows.
+ * @returns The rows, feeds carrying their tags.
+ */
+async function feedTags_annotate(items) {
+    const feedOf = (name) => {
+        const match = name.match(/^feed_(\d+)$/);
+        return match === null ? null : Number(match[1]);
+    };
+    if (!items.some((item) => feedOf(item.name) !== null))
+        return items;
+    const map = await feedTags_byFeed();
+    if (!map.ok) {
+        errorStack.stack_pop();
+        return items;
+    }
+    return items.map((item) => {
+        const feedId = feedOf(item.name);
+        const tags = feedId === null ? undefined : map.value.get(feedId);
+        return tags === undefined ? item : { ...item, tags };
+    });
+}
+/** The ChRIS session's filesystem. */
+export const chrisFilesystem = {
+    dispatcher: vfsDispatcher,
+    get cache() {
+        return listCache_get();
+    },
+    // /proc is backed by the process cache, which keeps its own freshness.
+    cache_holds: (path) => !path.startsWith('/proc'),
+    longRows_annotate: feedTags_annotate,
+    // chili's path walk is loaded when a listing first asks, not with the backend.
+    unreadLinks_take: async () => (await import('@fnndsc/chili/utils')).pathMapper_get().blindParents_take(),
+    structural: CHRIS_STRUCTURAL_PATHS,
+    folder_enter: chrisFolder_enter,
+    segment_title: chrisSegment_title,
+    path_physical: async (path) => {
+        const { path_resolveChrisFs } = await import('@fnndsc/chili/utils/cli.js');
+        return path_resolveChrisFs(path, {});
+    },
+};
+//# sourceMappingURL=filesystem.js.map

package/dist/chris/filesystem.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"filesystem.js","sourceRoot":"","sources":["../../src/chris/filesystem.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAC/D,OAAO,EAAU,UAAU,EAAE,MAAM,cAAc,CAAC;AAGlD,OAAO,EAAE,sBAAsB,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAEhG;;;;;;;GAOG;AACH,KAAK,UAAU,iBAAiB,CAAC,KAAoB;IACnD,MAAM,MAAM,GAAG,CAAC,IAAY,EAAiB,EAAE;QAC7C,MAAM,KAAK,GAA4B,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC;QAClE,OAAO,KAAK,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IAClD,CAAC,CAAC;IACF,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAiB,EAAW,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,IAAI,CAAC;QAAE,OAAO,KAAK,CAAC;IAC1F,MAAM,GAAG,GAAkC,MAAM,eAAe,EAAE,CAAC;IACnE,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;QACZ,UAAU,CAAC,SAAS,EAAE,CAAC;QACvB,OAAO,KAAK,CAAC;IACf,CAAC;IACD,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,IAAiB,EAAe,EAAE;QAClD,MAAM,MAAM,GAAkB,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAChD,MAAM,IAAI,GAAyB,MAAM,KAAK,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QACvF,OAAO,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,GAAG,IAAI,EAAE,IAAI,EAAE,CAAC;IACvD,CAAC,CAAC,CAAC;AACL,CAAC;AAED,sCAAsC;AACtC,MAAM,CAAC,MAAM,eAAe,GAAsB;IAChD,UAAU,EAAE,aAAa;IACzB,IAAI,KAAK;QACP,OAAO,aAAa,EAAE,CAAC;IACzB,CAAC;IACD,uEAAuE;IACvE,WAAW,EAAE,CAAC,IAAY,EAAW,EAAE,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC;IACjE,iBAAiB,EAAE,iBAAiB;IACpC,+EAA+E;IAC/E,gBAAgB,EAAE,KAAK,IAAuB,EAAE,CAAC,CAAC,MAAM,MAAM,CAAC,qBAAqB,CAAC,CAAC,CAAC,cAAc,EAAE,CAAC,iBAAiB,EAAE;IAC3H,UAAU,EAAE,sBAAsB;IAClC,YAAY,EAAE,iBAAiB;IAC/B,aAAa,EAAE,kBAAkB;IACjC,aAAa,EAAE,KAAK,EAAE,IAAY,EAAmB,EAAE;QACrD,MAAM,EAAE,mBAAmB,EAAE,GAAG,MAAM,MAAM,CAAC,4BAA4B,CAAC,CAAC;QAC3E,OAAO,mBAAmB,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;IACvC,CAAC;CACF,CAAC"}

package/dist/chris/help.d.ts

@@ -0,0 +1,16 @@
+/**
+ * @file The ChRIS backend's help: a page for each command it registers.
+ *
+ * The core's own commands keep their pages in `builtins/help.ts`; these are
+ * registered with the ChRIS commands, so a session without ChRIS has none.
+ *
+ * @module
+ */
+import type { CommandHelp } from '../core/commandRegistry.js';
+/**
+ * Standard subcommands and options injected into every resource help entry.
+ * Captures the Resource Contract documented in CONTEXT.md.
+ */
+export declare const RESOURCE_LIST_OPTIONS: string[];
+/** The help for each ChRIS command, by name. */
+export declare const chrisHelp: Record<string, CommandHelp>;