@fnndsc/brasa 0.55.3 → 0.56.1

package/dist/builtins/berth/berthCube.d.ts

@@ -0,0 +1,238 @@
+/**
+ * What stands at a ChRIS path.
+ *
+ * @example
+ * ```ts
+ * const entry: RemoteEntry = { kind: 'file', size: 1024 };
+ * ```
+ */
+export interface RemoteEntry {
+    /** A file, or a folder (a link to a folder counts as one). */
+    readonly kind: 'file' | 'folder';
+    /** A file's size in bytes; 0 for a folder. */
+    readonly size: number;
+}
+/**
+ * One file under a folder being anchored.
+ *
+ * @example
+ * ```ts
+ * const file: RemoteFile = { name: 'anat/t1.nii', source: '/home/alice/uploads/s/anat/t1.nii', size: 1024 };
+ * ```
+ */
+export interface RemoteFile {
+    /** Its name relative to the folder, with `/` between parts. */
+    readonly name: string;
+    /** The ChRIS path its bytes are read from, links followed. */
+    readonly source: string;
+    /** Its size in bytes. */
+    readonly size: number;
+}
+/**
+ * One file's bytes as ChRIS sent them: a stream, or a PACS file whole.
+ *
+ * @example
+ * ```ts
+ * const bytes: RemoteBytes = { stream: Buffer.from('DICM') };
+ * ```
+ */
+export interface RemoteBytes {
+    /** The bytes: a stream to read, or the whole file. */
+    readonly stream: NodeJS.ReadableStream | Buffer;
+}
+/**
+ * The person's home in ChRIS, `/home/<user>`.
+ *
+ * @returns The home the session names; `/` when no session is installed.
+ *
+ * @example
+ * ```ts
+ * await berthHome_get(); // '/home/alice'
+ * ```
+ */
+export declare function berthHome_get(): Promise<string>;
+/**
+ * A typed path as an absolute ChRIS path: relative to the working directory,
+ * `~` for the home, and a `/proc/jobs/…/data` path through the job's link
+ * to the output it names, as `ls` and `download` enter it.
+ *
+ * @param typed - The path as typed.
+ * @returns The absolute path.
+ *
+ * @example
+ * ```ts
+ * await berthPath_resolve('~/uploads/weights'); // '/home/alice/uploads/weights'
+ * ```
+ */
+export declare function berthPath_resolve(typed: string): Promise<string>;
+/**
+ * What stands at a path: a file with its size, a folder, or nothing.
+ *
+ * @param target - An absolute ChRIS path.
+ * @returns The entry, or null when nothing of that name is in its folder.
+ * @throws {Error} When the folder holding it cannot be listed.
+ *
+ * @example
+ * ```ts
+ * await remoteEntry_read('/home/alice/uploads/t1.nii'); // { kind: 'file', size: 1024 }
+ * ```
+ */
+export declare function remoteEntry_read(target: string): Promise<RemoteEntry | null>;
+/**
+ * Every file under a ChRIS folder, with its size and the path to read it at.
+ *
+ * @param folder - An absolute ChRIS path (logical: the folder as the person sees it).
+ * @returns The files, by name relative to the folder; empty for an empty folder.
+ * @throws {Error} When a folder under it cannot be listed.
+ *
+ * @example
+ * ```ts
+ * await remoteTree_list('/home/alice/uploads/s'); // [{ name: 'anat/t1.nii', source: '/home/alice/uploads/s/anat/t1.nii', size: 1024 }]
+ * ```
+ */
+export declare function remoteTree_list(folder: string): Promise<RemoteFile[]>;
+/**
+ * One ChRIS file as a file to read: its path with links followed.
+ *
+ * @param file - An absolute ChRIS path to a file.
+ * @param size - Its size in bytes.
+ * @returns The file, named by its last part.
+ *
+ * @example
+ * ```ts
+ * await remoteFile_locate('/home/alice/uploads/t1.nii', 1024); // { name: 't1.nii', source: '/home/alice/uploads/t1.nii', size: 1024 }
+ * ```
+ */
+export declare function remoteFile_locate(file: string, size: number): Promise<RemoteFile>;
+/**
+ * A plugin instance's status, as CUBE reports it.
+ *
+ * @param instanceId - The plugin instance's id.
+ * @returns Its status (`finishedSuccessfully`, `started`, …).
+ * @throws {Error} When CUBE does not answer for it.
+ *
+ * @example
+ * ```ts
+ * await nodeStatus_get(41); // 'finishedSuccessfully'
+ * ```
+ */
+export declare function nodeStatus_get(instanceId: number): Promise<string>;
+/**
+ * One ChRIS file's bytes, as the kernel reads them with the session's token.
+ *
+ * @param source - The file's path (physical).
+ * @returns Its bytes: a stream, or a PACS file whole as a Buffer.
+ * @throws {Error} When ChRIS does not give the bytes.
+ *
+ * @example
+ * ```ts
+ * const bytes: RemoteBytes = await remoteFile_open('/home/alice/uploads/t1.nii');
+ * ```
+ */
+export declare function remoteFile_open(source: string): Promise<RemoteBytes>;
+/**
+ * What a plugin run or a feed's start answered: the plugin instance made, or
+ * CUBE's reason for making none.
+ *
+ * @example
+ * ```ts
+ * const made: AttachOutcome = { ok: true, instance: 57, feed: 5, pluginName: 'pl-dsdircopy' };
+ * const refused: AttachOutcome = { ok: false, reason: 'No matching plugins found' };
+ * ```
+ */
+export type AttachOutcome = AttachMade | AttachRefused;
+/** A plugin instance made. */
+export interface AttachMade {
+    /** The instance was made. */
+    readonly ok: true;
+    /** Its id. */
+    readonly instance: number;
+    /** The feed it is in; null when CUBE did not say. */
+    readonly feed: number | null;
+    /** The plugin's name, as CUBE gave it. */
+    readonly pluginName: string;
+}
+/** No plugin instance made, and why. */
+export interface AttachRefused {
+    /** No instance was made. */
+    readonly ok: false;
+    /** CUBE's reason, as the kernel stacked it. */
+    readonly reason: string;
+}
+/**
+ * What an upload of a folder's contents did.
+ *
+ * @example
+ * ```ts
+ * const sent: UploadOutcome = { files: 3, bytes: 1024, failed: 0 };
+ * ```
+ */
+export interface UploadOutcome {
+    /** The files that reached ChRIS. */
+    readonly files: number;
+    /** Their bytes. */
+    readonly bytes: number;
+    /** The files that did not. */
+    readonly failed: number;
+}
+/**
+ * Uploads everything inside a local folder into a ChRIS folder: each entry
+ * keeps its name under the target, a folder with all it holds, hidden files
+ * too. It is the upload `upload` runs, with its progress, entry by entry, so
+ * the local folder's own name is not added to the target.
+ *
+ * @param local - The local folder.
+ * @param target - The ChRIS folder, absolute; the upload makes it.
+ * @returns What reached ChRIS and what did not.
+ * @throws {Error} When the upload cannot start (a local entry that cannot be read).
+ *
+ * @example
+ * ```ts
+ * await folderContents_upload('/outgoing', '/home/alice/berth/0b6c…'); // { files: 3, bytes: 1024, failed: 0 }
+ * ```
+ */
+export declare function folderContents_upload(local: string, target: string): Promise<UploadOutcome>;
+/**
+ * Runs a registered plugin by name as a child of a plugin instance, as a
+ * line run in that node's folder does: the version CUBE lists first under
+ * that exact name.
+ *
+ * @param plugin - The plugin's name, `pl-dsdircopy`.
+ * @param parent - The plugin instance it runs after.
+ * @param parameters - Its parameters by name (`dir`), and `title` for the node.
+ * @returns The instance made, or CUBE's reason.
+ *
+ * @example
+ * ```ts
+ * await pluginChild_run('pl-dsdircopy', 41, { dir: '/home/alice/berth/0b6c…', title: 'berth work' });
+ * ```
+ */
+export declare function pluginChild_run(plugin: string, parent: number, parameters: Readonly<Record<string, string>>): Promise<AttachOutcome>;
+/**
+ * Starts a new feed from `pl-dircopy` over some ChRIS paths: its `dir` is
+ * the paths joined by commas, as the fs plugin takes several, and its title
+ * names the feed, as CUBE names a feed after its root.
+ *
+ * @param paths - The ChRIS paths, absolute.
+ * @param name - The feed's name, the root node's title.
+ * @returns The root instance made with its feed, or CUBE's reason.
+ *
+ * @example
+ * ```ts
+ * await feedRoot_create(['/home/alice/uploads/weights', '/PUBLIC/atlas'], 'berth work');
+ * ```
+ */
+export declare function feedRoot_create(paths: readonly string[], name: string): Promise<AttachOutcome>;
+/**
+ * Names a feed.
+ *
+ * @param feed - The feed's id.
+ * @param name - Its name.
+ * @returns Null when CUBE took it; else CUBE's reason.
+ *
+ * @example
+ * ```ts
+ * await feedName_set(12, 'seg run'); // null
+ * ```
+ */
+export declare function feedName_set(feed: number, name: string): Promise<string | null>;

package/dist/builtins/berth/berthCube.js

@@ -0,0 +1,366 @@
+/**
+ * @file What the `berth` verbs ask of ChRIS: a path resolved as the session
+ * resolves it, what stands there, every file beneath it with its size, a
+ * plugin instance's status and one file's bytes, for an anchor; and for a
+ * close, a local folder uploaded into the person's files, a ds plugin run as
+ * a child of a node, and a feed started from an fs plugin over some paths.
+ *
+ * Every read goes through the session's own kernel (salsa, with the
+ * session's token), so an anchor reads only what ChRIS lets that person
+ * read. A folder is walked through the session's dispatcher, its links
+ * followed to the folders they name (a node's output that is a link to a
+ * PACS series, an upload a feed was made from). A PACS file comes back whole,
+ * as a Buffer, where any other comes back as a stream; both are handed on.
+ *
+ * Key components:
+ * - RemoteEntry, RemoteFile, RemoteBytes: what the reads answer.
+ * - berthHome_get: the person's home in ChRIS.
+ * - berthPath_resolve: a typed path as an absolute ChRIS path.
+ * - remoteEntry_read: what stands at a path, a file or a folder.
+ * - remoteTree_list: every file under a folder, with its size and where to read it.
+ * - nodeStatus_get: a plugin instance's status, as CUBE reports it.
+ * - remoteFile_open: one file's bytes, a stream or a Buffer.
+ * - folderContents_upload: everything inside a local folder, into a ChRIS folder.
+ * - pluginChild_run: a registered plugin run by name as a child of a plugin instance.
+ * - feedRoot_create: a new feed whose root is `pl-dircopy` over some paths.
+ * - feedName_set: a feed named.
+ * - AttachOutcome, UploadOutcome: what those answer.
+ *
+ * Typical usage:
+ * ```ts
+ * const path: string = await berthPath_resolve('~/uploads/weights');
+ * const files: RemoteFile[] = await remoteTree_list(path);
+ * const bytes: RemoteBytes = await remoteFile_open(files[0].source);
+ * ```
+ *
+ * Dependencies: a connected ChRIS session (salsa); the session's dispatcher
+ * and path mapper; chili's folder upload, the one `upload` runs. Sizes are
+ * bytes. A run or a feed CUBE refuses answers with CUBE's reason, as the
+ * kernel stacked it.
+ *
+ * @module
+ */
+import { readdirSync } from 'node:fs';
+import { join, posix } from 'node:path';
+import { errorStack } from '@fnndsc/fond';
+import { backendInstalled_get } from '../../core/backend.js';
+import { error_stripDebugPrefix } from '../../core/errorText.js';
+import { vfsDispatcher_get } from '../../core/filesystem.js';
+import { path_resolve } from '../../core/paths.js';
+import { sink_get } from '../../core/sink.js';
+/** A `/proc/jobs` path at or under a job's `data` link: the link, and what follows it. */
+const PROC_DATA_PATH = /^(\/proc\/jobs\/feed_\d+(?:\/[^/]+_\d+)+\/data)(\/.*)?$/;
+/** Listing kinds that are folders to walk into. */
+const FOLDER_KINDS = new Set(['dir', 'vfs']);
+/**
+ * The person's home in ChRIS, `/home/<user>`.
+ *
+ * @returns The home the session names; `/` when no session is installed.
+ *
+ * @example
+ * ```ts
+ * await berthHome_get(); // '/home/alice'
+ * ```
+ */
+export async function berthHome_get() {
+    return (await backendInstalled_get()?.session.home_get()) ?? '/';
+}
+/**
+ * A typed path as an absolute ChRIS path: relative to the working directory,
+ * `~` for the home, and a `/proc/jobs/…/data` path through the job's link
+ * to the output it names, as `ls` and `download` enter it.
+ *
+ * @param typed - The path as typed.
+ * @returns The absolute path.
+ *
+ * @example
+ * ```ts
+ * await berthPath_resolve('~/uploads/weights'); // '/home/alice/uploads/weights'
+ * ```
+ */
+export async function berthPath_resolve(typed) {
+    const resolved = await path_resolve(typed);
+    const link = resolved.match(PROC_DATA_PATH);
+    if (link === null)
+        return resolved;
+    const target = await vfsDispatcher_get().linkTarget_resolve(link[1]);
+    return target.ok ? `${target.value}${link[2] ?? ''}` : resolved;
+}
+/**
+ * The path CUBE stores a logical path at, links followed; the path as given
+ * when it maps to nothing else.
+ *
+ * @param logical - An absolute ChRIS path.
+ * @returns The physical path.
+ */
+async function physicalPath_get(logical) {
+    try {
+        const { logicalPath_resolve } = await import('@fnndsc/chili/utils');
+        const physical = await logicalPath_resolve(logical);
+        return physical.ok ? physical.value : logical;
+    }
+    catch {
+        return logical;
+    }
+}
+/**
+ * Lists one folder through the session's dispatcher.
+ *
+ * @param folder - The folder.
+ * @returns Its entries.
+ * @throws {Error} When it cannot be listed: a walk must not read an unlistable folder as an empty one.
+ */
+async function folder_list(folder) {
+    const listed = await vfsDispatcher_get().list(folder);
+    if (!listed.ok)
+        throw new Error(`cannot list ${folder}`);
+    return listed.value;
+}
+/**
+ * What stands at a path: a file with its size, a folder, or nothing.
+ *
+ * @param target - An absolute ChRIS path.
+ * @returns The entry, or null when nothing of that name is in its folder.
+ * @throws {Error} When the folder holding it cannot be listed.
+ *
+ * @example
+ * ```ts
+ * await remoteEntry_read('/home/alice/uploads/t1.nii'); // { kind: 'file', size: 1024 }
+ * ```
+ */
+export async function remoteEntry_read(target) {
+    if (target === '/')
+        return { kind: 'folder', size: 0 };
+    const items = await folder_list(posix.dirname(target));
+    const found = items.find((item) => item.name === posix.basename(target));
+    if (found === undefined)
+        return null;
+    return found.type === 'file' ? { kind: 'file', size: found.size } : { kind: 'folder', size: 0 };
+}
+/**
+ * Every file under a folder, walked depth first, links followed to the
+ * folders they name; a folder already walked is not walked again.
+ *
+ * @param folder - The folder as listed (a physical path).
+ * @param prefix - The relative name of the folder under the anchor ('' at its top).
+ * @param seen - Folders already walked.
+ * @returns The files.
+ * @throws {Error} When a folder under it cannot be listed.
+ */
+async function folderFiles_walk(folder, prefix, seen) {
+    if (seen.has(folder))
+        return [];
+    seen.add(folder);
+    const files = [];
+    for (const item of await folder_list(folder)) {
+        const name = prefix === '' ? item.name : `${prefix}/${item.name}`;
+        const here = posix.join(folder, item.name);
+        if (item.type === 'file') {
+            files.push({ name, source: here, size: item.size });
+        }
+        else if (FOLDER_KINDS.has(item.type)) {
+            files.push(...await folderFiles_walk(here, name, seen));
+        }
+        else if (item.type === 'link' && item.target !== undefined && item.target !== '') {
+            const target = item.target.startsWith('/') ? item.target : posix.join(folder, item.target);
+            files.push(...await folderFiles_walk(target, name, seen));
+        }
+    }
+    return files;
+}
+/**
+ * Every file under a ChRIS folder, with its size and the path to read it at.
+ *
+ * @param folder - An absolute ChRIS path (logical: the folder as the person sees it).
+ * @returns The files, by name relative to the folder; empty for an empty folder.
+ * @throws {Error} When a folder under it cannot be listed.
+ *
+ * @example
+ * ```ts
+ * await remoteTree_list('/home/alice/uploads/s'); // [{ name: 'anat/t1.nii', source: '/home/alice/uploads/s/anat/t1.nii', size: 1024 }]
+ * ```
+ */
+export async function remoteTree_list(folder) {
+    return folderFiles_walk(await physicalPath_get(folder), '', new Set());
+}
+/**
+ * One ChRIS file as a file to read: its path with links followed.
+ *
+ * @param file - An absolute ChRIS path to a file.
+ * @param size - Its size in bytes.
+ * @returns The file, named by its last part.
+ *
+ * @example
+ * ```ts
+ * await remoteFile_locate('/home/alice/uploads/t1.nii', 1024); // { name: 't1.nii', source: '/home/alice/uploads/t1.nii', size: 1024 }
+ * ```
+ */
+export async function remoteFile_locate(file, size) {
+    return { name: posix.basename(file), source: await physicalPath_get(file), size };
+}
+/**
+ * A plugin instance's status, as CUBE reports it.
+ *
+ * @param instanceId - The plugin instance's id.
+ * @returns Its status (`finishedSuccessfully`, `started`, …).
+ * @throws {Error} When CUBE does not answer for it.
+ *
+ * @example
+ * ```ts
+ * await nodeStatus_get(41); // 'finishedSuccessfully'
+ * ```
+ */
+export async function nodeStatus_get(instanceId) {
+    const { job_statusFetch } = await import('@fnndsc/salsa');
+    const status = await job_statusFetch(instanceId);
+    if (!status.ok)
+        throw new Error(`cannot read the status of plugin instance ${instanceId}`);
+    return status.value;
+}
+/**
+ * One ChRIS file's bytes, as the kernel reads them with the session's token.
+ *
+ * @param source - The file's path (physical).
+ * @returns Its bytes: a stream, or a PACS file whole as a Buffer.
+ * @throws {Error} When ChRIS does not give the bytes.
+ *
+ * @example
+ * ```ts
+ * const bytes: RemoteBytes = await remoteFile_open('/home/alice/uploads/t1.nii');
+ * ```
+ */
+export async function remoteFile_open(source) {
+    const { fileContent_getBinaryStream } = await import('@fnndsc/salsa');
+    const opened = await fileContent_getBinaryStream(source);
+    if (!opened.ok)
+        throw new Error(`cannot read ${source}`);
+    const stream = opened.value.stream;
+    if (Buffer.isBuffer(stream))
+        return { stream };
+    return { stream: stream };
+}
+/**
+ * CUBE's reason for a refusal: what the kernel stacked since a mark, taken off the stack.
+ *
+ * @param mark - The stack's mark before the call.
+ * @param fallback - The words when nothing was stacked.
+ * @returns The reason.
+ */
+function cubeReason_take(mark, fallback) {
+    const stacked = errorStack.checkpoint_drain(mark);
+    const words = stacked.map((message) => error_stripDebugPrefix(message.message).trim()).filter((message) => message !== '');
+    return words.length > 0 ? words.join('; ') : fallback;
+}
+/**
+ * Uploads everything inside a local folder into a ChRIS folder: each entry
+ * keeps its name under the target, a folder with all it holds, hidden files
+ * too. It is the upload `upload` runs, with its progress, entry by entry, so
+ * the local folder's own name is not added to the target.
+ *
+ * @param local - The local folder.
+ * @param target - The ChRIS folder, absolute; the upload makes it.
+ * @returns What reached ChRIS and what did not.
+ * @throws {Error} When the upload cannot start (a local entry that cannot be read).
+ *
+ * @example
+ * ```ts
+ * await folderContents_upload('/outgoing', '/home/alice/berth/0b6c…'); // { files: 3, bytes: 1024, failed: 0 }
+ * ```
+ */
+export async function folderContents_upload(local, target) {
+    const { files_uploadWithProgress } = await import('@fnndsc/chili/commands/fs/upload.js');
+    let files = 0;
+    let bytes = 0;
+    let failed = 0;
+    for (const name of readdirSync(local).sort()) {
+        const summary = await files_uploadWithProgress(join(local, name), target, {
+            expandLocalGlob: false,
+            force: true,
+            onNotice: (message, channel) => {
+                if (channel === 'err')
+                    sink_get().err_write(`${message}\n`);
+            },
+            onProgress: (event) => sink_get().progress_write({ ...event, label: name }),
+        });
+        files += summary.transferredCount;
+        bytes += summary.transferSize;
+        failed += summary.failedCount;
+    }
+    const { listCache_get } = await import('@fnndsc/cumin');
+    listCache_get().cache_invalidateTree(target);
+    listCache_get().cache_invalidate(posix.dirname(target));
+    return { files, bytes, failed };
+}
+/**
+ * Runs a registered plugin by name as a child of a plugin instance, as a
+ * line run in that node's folder does: the version CUBE lists first under
+ * that exact name.
+ *
+ * @param plugin - The plugin's name, `pl-dsdircopy`.
+ * @param parent - The plugin instance it runs after.
+ * @param parameters - Its parameters by name (`dir`), and `title` for the node.
+ * @returns The instance made, or CUBE's reason.
+ *
+ * @example
+ * ```ts
+ * await pluginChild_run('pl-dsdircopy', 41, { dir: '/home/alice/berth/0b6c…', title: 'berth work' });
+ * ```
+ */
+export async function pluginChild_run(plugin, parent, parameters) {
+    const { plugin_run } = await import('@fnndsc/salsa');
+    const mark = errorStack.checkpoint_mark();
+    const made = await plugin_run(`name_exact:${plugin}`, { ...parameters, previous_id: parent });
+    const instance = made?.['id'];
+    if (made === null || typeof instance !== 'number')
+        return { ok: false, reason: cubeReason_take(mark, `CUBE made no ${plugin} instance`) };
+    errorStack.checkpoint_drain(mark);
+    const feed = made['feed_id'];
+    const pluginName = made['plugin_name'];
+    return { ok: true, instance, feed: typeof feed === 'number' ? feed : null, pluginName: typeof pluginName === 'string' ? pluginName : plugin };
+}
+/**
+ * Starts a new feed from `pl-dircopy` over some ChRIS paths: its `dir` is
+ * the paths joined by commas, as the fs plugin takes several, and its title
+ * names the feed, as CUBE names a feed after its root.
+ *
+ * @param paths - The ChRIS paths, absolute.
+ * @param name - The feed's name, the root node's title.
+ * @returns The root instance made with its feed, or CUBE's reason.
+ *
+ * @example
+ * ```ts
+ * await feedRoot_create(['/home/alice/uploads/weights', '/PUBLIC/atlas'], 'berth work');
+ * ```
+ */
+export async function feedRoot_create(paths, name) {
+    const { feed_create } = await import('@fnndsc/salsa');
+    const mark = errorStack.checkpoint_mark();
+    const made = await feed_create([...paths], { title: name });
+    const instance = made?.pluginInstance.data.id;
+    if (made === null || typeof instance !== 'number')
+        return { ok: false, reason: cubeReason_take(mark, 'CUBE made no feed') };
+    errorStack.checkpoint_drain(mark);
+    return { ok: true, instance, feed: made.id, pluginName: 'pl-dircopy' };
+}
+/**
+ * Names a feed.
+ *
+ * @param feed - The feed's id.
+ * @param name - Its name.
+ * @returns Null when CUBE took it; else CUBE's reason.
+ *
+ * @example
+ * ```ts
+ * await feedName_set(12, 'seg run'); // null
+ * ```
+ */
+export async function feedName_set(feed, name) {
+    const { feed_rename } = await import('@fnndsc/cumin');
+    const mark = errorStack.checkpoint_mark();
+    const renamed = await feed_rename(feed, name);
+    if (!renamed.ok)
+        return cubeReason_take(mark, `CUBE did not name feed ${feed}`);
+    errorStack.checkpoint_drain(mark);
+    return null;
+}
+//# sourceMappingURL=berthCube.js.map

package/dist/builtins/berth/berthCube.js.map

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

package/dist/builtins/berth/berthDisk.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The bytes free on the filesystem holding a folder, for an unprivileged
+ * user: the blocks available to one, not those kept for root.
+ *
+ * @param folder - The folder.
+ * @returns Free bytes.
+ *
+ * @example
+ * ```ts
+ * freeBytes_get('/anchors'); // 85899345920
+ * ```
+ */
+export declare function freeBytes_get(folder: string): number;

package/dist/builtins/berth/berthDisk.js

@@ -0,0 +1,34 @@
+/**
+ * @file The room a berth's disk has: the bytes free on the filesystem that
+ * holds a folder.
+ *
+ * Key components:
+ * - freeBytes_get: the bytes an unprivileged user may still write there.
+ *
+ * Typical usage:
+ * ```ts
+ * const room: number = freeBytes_get('/anchors');
+ * ```
+ *
+ * Dependencies: Node.js built-ins only (`statfs`).
+ *
+ * @module
+ */
+import { statfsSync } from 'node:fs';
+/**
+ * The bytes free on the filesystem holding a folder, for an unprivileged
+ * user: the blocks available to one, not those kept for root.
+ *
+ * @param folder - The folder.
+ * @returns Free bytes.
+ *
+ * @example
+ * ```ts
+ * freeBytes_get('/anchors'); // 85899345920
+ * ```
+ */
+export function freeBytes_get(folder) {
+    const stats = statfsSync(folder);
+    return Number(stats.bavail) * Number(stats.bsize);
+}
+//# sourceMappingURL=berthDisk.js.map

package/dist/builtins/berth/berthDisk.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"berthDisk.js","sourceRoot":"","sources":["../../../src/builtins/berth/berthDisk.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,EAAE,UAAU,EAAgB,MAAM,SAAS,CAAC;AAEnD;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,aAAa,CAAC,MAAc;IAC1C,MAAM,KAAK,GAAY,UAAU,CAAC,MAAM,CAAC,CAAC;IAC1C,OAAO,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;AACpD,CAAC"}