@fnndsc/brasa 0.36.0 → 0.37.0

package/dist/builtins/helpSections.js

@@ -0,0 +1,237 @@
+/**
+ * @file help's sections: the table of contents `help` shows, a section's
+ * page (`help PACS`), the Shell topics (`help pipes`), and `apropos`.
+ *
+ * Borrowed from man rather than reinvented: sections by topic (man's are by
+ * number), a page per command, and `apropos` / `man -k` to search every
+ * summary by a word, which is how anyone finds a command they cannot name.
+ * A section is one capitalised word, so `help PACS` (the section) and
+ * `help pacs` (the command) never collide; a section word that names no
+ * command answers in lower case too.
+ *
+ * @module
+ */
+import chalk from 'chalk';
+/** The sections, in the order `help` lists them. */
+export const HELP_SECTIONS = [
+    { name: 'Navigation', blurb: "Move around ChRIS's filesystem, including the /proc and /net projections.", examples: ['cd', 'ls', 'tree', 'du', 'cubepath'] },
+    { name: 'Files', blurb: 'Read, write, copy and move files and folders; upload from and download to this machine.', examples: ['cat', 'cp', 'mv', 'upload', 'download', 'grep'] },
+    { name: 'Sharing', blurb: 'Who may see a folder or file, and links that open ARGUS where you are.', examples: ['chmod', 'setfacl', 'url'] },
+    { name: 'Connection', blurb: 'Who you are, which CUBE you are on, and where the session stands.', examples: ['connect', 'whoami', 'context'] },
+    { name: 'Monitoring', blurb: 'Live jobs as a filesystem, and jumping to one by number.', examples: ['proc'] },
+    { name: 'Imaging', blurb: 'DICOM tags and image viewing.', examples: ['dcm', 'image'] },
+    { name: 'Workflows', blurb: 'Gather a cohort, record what you do as a manifest, and replay it.', examples: ['gather', 'record', 'play', 'expect'] },
+    { name: 'Resources', blurb: 'ChRIS resources one at a time or as lists: feeds, plugins, pipelines, jobs, tags, groups, compute, store.', examples: ['feed', 'feeds', 'plugins', 'jobs'] },
+    { name: 'PACS', blurb: "Ask a PACS for a patient's studies and series, narrow the answer, and pull it into ChRIS.", examples: ['query', 'pull', 'pacs'] },
+    { name: 'Admin', blurb: 'Administrative acts that need elevated rights.', examples: ['sudo', 'user'] },
+    { name: 'Settings', blurb: 'How the shell behaves: prompt, timing, physical paths, debug output.', examples: ['prompt', 'timing', 'debug'] },
+    { name: 'Games', blurb: 'The /usr/games shelf: text toys, small utilities and games.', examples: ['fortune', 'cowsay', 'tetris'] },
+    { name: 'General', blurb: 'Help, finding a command by a word, release notes, versions, and leaving.', examples: ['help', 'apropos', 'notes', 'version', 'exit'] },
+];
+/** The section that is not a list of commands: what the shell does to a line. */
+export const SHELL_SECTION = {
+    name: 'Shell',
+    blurb: 'What the shell does to a line: pipes, redirection, index handles (@SER3), pronouns (${cwd}), listing-aware grep, command.',
+    examples: ['help pipes', 'help handles', 'help pronouns'],
+};
+/** The Shell section's topics, each `help <topic>`. */
+export const SHELL_TOPICS = [
+    {
+        name: 'pipes',
+        summary: 'cmd | cmd: text between programs, a numbered listing between builtins',
+        page: [
+            'A pipe hands one command\'s output to the next: cat notes.txt | wc -l.',
+            '',
+            'Between two builtins a numbered listing travels beside the text, so the',
+            'next builtin receives rows, not words:',
+            '  query PatientID:1234567 | grep -i t1 | gather add',
+            'A program that is not a builtin (sort, awk, a system grep) receives the',
+            'text alone. The last listing a pipe produces becomes the held listing:',
+            '@SER3 and ${listing} name its rows afterwards.',
+        ],
+    },
+    {
+        name: 'redirection',
+        summary: '> and >>: write or append a command\'s output to a file on this machine',
+        page: [
+            'cmd > file writes the output to a file; cmd >> file appends to it.',
+            '',
+            'The file is on the machine chell runs on, not in ChRIS: to put text in',
+            'ChRIS use touch --withContents or upload.',
+            '  query PatientID:1234567 --table > answer.txt',
+        ],
+    },
+    {
+        name: 'handles',
+        summary: '@SER3 @STD1-4 @FIL2,5,7: name rows of the last numbered listing',
+        page: [
+            'A listing that numbers its rows (query, query --table, gather list,',
+            'ls -l) prints a handle beside each: @PAT1, @STD3, @SER12, @DIR4, @FIL2.',
+            'Typed in a later line, a handle stands for its row:',
+            '  gather add @SER3        one row',
+            '  gather add @SER1-4      a range',
+            '  gather add @SER2,5,7    a list',
+            '',
+            'The listing\'s footer says what is numbered now:',
+            '  numbered: @PAT1, @STD1-9, @SER1-235',
+            'The next listing replaces it, so @SER3 always means the last listing\'s',
+            'row. grep keeps the handles rows already wore (@SER41 stays @SER41).',
+        ],
+    },
+    { name: 'pronouns', summary: '${cwd} ${listing} …: what this session just made or asked' },
+    { name: 'grep', summary: 'filter text, or a numbered listing keeping its handles' },
+    { name: 'command', summary: 'run the system program, not the builtin' },
+];
+/** Wraps a paragraph to a width, each line indented. */
+function paragraph_wrap(text, indent, width = 78) {
+    const lines = [];
+    let line = '';
+    for (const word of text.split(/\s+/)) {
+        if (line !== '' && indent.length + line.length + 1 + word.length > width) {
+            lines.push(`${indent}${line}`);
+            line = word;
+        }
+        else {
+            line = line === '' ? word : `${line} ${word}`;
+        }
+    }
+    if (line !== '')
+        lines.push(`${indent}${line}`);
+    return lines;
+}
+/**
+ * A section's commands: those that declare it, and for Games the shelf.
+ *
+ * @param section - The section's name.
+ * @param lookup - The commands.
+ * @returns Its runnable commands.
+ */
+export function sectionCommands_of(section, lookup) {
+    const declared = lookup.commands().filter((name) => lookup.section(name) === section);
+    if (section !== 'Games')
+        return declared;
+    return [...new Set([...declared, ...lookup.games()])];
+}
+/**
+ * `help`: the table of contents. A section with nothing this session can
+ * run is left out, as are examples it cannot run.
+ *
+ * @param lookup - The commands.
+ * @returns The page.
+ */
+export function helpToc_render(lookup) {
+    const runnable = new Set(lookup.commands());
+    const out = [
+        '',
+        chalk.bold.yellow('chell — the ChRIS shell'),
+        chalk.gray('Type help <Section> for a section, help <command> for a command, apropos <word> to search.'),
+        '',
+    ];
+    const entry = (section, count) => {
+        out.push(`${chalk.bold.cyan(section.name)}${count === null ? '' : chalk.gray(`  (${count})`)}`);
+        out.push(...paragraph_wrap(section.blurb, '    '));
+        const shown = section === SHELL_SECTION ? [...section.examples] : section.examples.filter((name) => runnable.has(name) || lookup.games().includes(name));
+        if (shown.length > 0)
+            out.push(`    ${chalk.gray('e.g.')}  ${shown.map((name) => chalk.yellow(name)).join('  ')}`);
+        out.push('');
+    };
+    for (const section of HELP_SECTIONS) {
+        const count = sectionCommands_of(section.name, lookup).length;
+        if (count > 0)
+            entry(section, count);
+    }
+    entry(SHELL_SECTION, null);
+    if (runnable.has('query') && runnable.has('gather')) {
+        out.push(`${chalk.gray('Start here:')}  ${chalk.yellow('query PatientID:1234567 | grep -i t1 | gather add')}`, '');
+    }
+    return `${out.join('\n')}\n`;
+}
+/**
+ * The section a word names: exactly (`PACS`), or in any case when no command
+ * has that name (`navigation`).
+ *
+ * @param word - What followed `help`.
+ * @param isCommand - Whether a command has that name.
+ * @returns The section, or undefined.
+ */
+export function section_find(word, isCommand) {
+    const all = [...HELP_SECTIONS, SHELL_SECTION];
+    const exact = all.find((section) => section.name === word);
+    if (exact !== undefined)
+        return exact;
+    if (isCommand(word))
+        return undefined;
+    return all.find((section) => section.name.toLowerCase() === word.toLowerCase());
+}
+/**
+ * A section's page: what it is for, then each command with its line.
+ *
+ * @param section - The section.
+ * @param lookup - The commands.
+ * @returns The page.
+ */
+export function helpSection_render(section, lookup) {
+    const out = ['', `${chalk.bold.cyan(section.name)} ${chalk.gray('—')} ${section.blurb}`, ''];
+    const rows = section === SHELL_SECTION
+        ? SHELL_TOPICS.map((topic) => ({ name: topic.name, line: topic.summary }))
+        : sectionCommands_of(section.name, lookup).map((name) => ({ name, line: lookup.summary(name) ?? '' }));
+    const width = Math.max(12, ...rows.map((row) => row.name.length + 2));
+    for (const row of rows)
+        out.push(`  ${chalk.cyan(row.name.padEnd(width))}${row.line}`);
+    out.push('', chalk.gray(`help <${section === SHELL_SECTION ? 'topic' : 'command'}> for each.`), '');
+    return `${out.join('\n')}\n`;
+}
+/**
+ * A Shell topic's own page, or undefined when it is not one (or is a
+ * command, whose own page answers).
+ *
+ * @param word - What followed `help`.
+ * @returns The page.
+ */
+export function shellTopic_render(word) {
+    const topic = SHELL_TOPICS.find((one) => one.name === word && one.page !== undefined);
+    if (topic === undefined || topic.page === undefined)
+        return undefined;
+    return `\n${chalk.bold.yellow(topic.name.toUpperCase())}\n${chalk.gray('─'.repeat(60))}\n${topic.page.join('\n')}\n\n${chalk.gray('help Shell for the other topics.')}\n`;
+}
+/**
+ * `apropos <word>` (`man -k`): what holds the word, strongest first. A
+ * section, a command or a Shell topic whose name or one line holds it leads;
+ * one that only mentions it further in (its description, its options)
+ * follows, under "also mentioned in", so `apropos dicom` leads with dcm and
+ * image rather than a game that happens to name DICOM.
+ *
+ * @param word - What to look for.
+ * @param lookup - The commands.
+ * @returns The lines, empty when nothing holds the word.
+ */
+export function apropos_search(word, lookup) {
+    const needle = word.toLowerCase();
+    const holds = (text) => text.toLowerCase().includes(needle);
+    const strong = [];
+    const mentioned = [];
+    for (const section of [...HELP_SECTIONS, SHELL_SECTION]) {
+        if (holds(`${section.name} ${section.blurb}`))
+            strong.push(`${chalk.cyan(section.name)} ${chalk.gray('(section)')} — ${section.blurb}`);
+    }
+    for (const name of lookup.commands()) {
+        const line = `${chalk.cyan(name)} ${chalk.gray(`(${lookup.section(name) ?? 'General'})`)} — ${lookup.summary(name) ?? ''}`;
+        if (holds(`${name} ${lookup.summary(name) ?? ''}`))
+            strong.push(line);
+        else if (holds(lookup.text(name)))
+            mentioned.push(line);
+    }
+    for (const topic of SHELL_TOPICS) {
+        if (lookup.commands().includes(topic.name))
+            continue;
+        const line = `${chalk.cyan(topic.name)} ${chalk.gray('(Shell)')} — ${topic.summary}`;
+        if (holds(`${topic.name} ${topic.summary}`))
+            strong.push(line);
+        else if (holds((topic.page ?? []).join(' ')))
+            mentioned.push(line);
+    }
+    if (mentioned.length === 0)
+        return strong;
+    return [...strong, ...(strong.length > 0 ? [''] : []), chalk.gray('also mentioned in:'), ...mentioned];
+}
+//# sourceMappingURL=helpSections.js.map

package/dist/builtins/helpSections.js.map

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

package/dist/builtins/sys/apropos.d.ts

@@ -0,0 +1,22 @@
+/**
+ * @file apropos and man: find a command by a word, and read its page, in the
+ * words every Unix hand already knows (builtins/helpSections.ts).
+ *
+ * @module
+ */
+import { CommandEnvelope } from '@fnndsc/menu';
+/**
+ * `apropos <word>`: every command, section and Shell topic whose name,
+ * summary or description holds the word.
+ *
+ * @param args - The word (several words are one phrase).
+ * @returns The matches, or nothing appropriate (exit 1, as apropos does).
+ */
+export declare function builtin_apropos(args: string[]): Promise<CommandEnvelope>;
+/**
+ * `man <command|Section|topic>` is `help` for it; `man -k <word>` is apropos.
+ *
+ * @param args - The words after `man`.
+ * @returns The page, or the matches.
+ */
+export declare function builtin_man(args: string[]): Promise<CommandEnvelope>;

package/dist/builtins/sys/apropos.js

@@ -0,0 +1,41 @@
+/**
+ * @file apropos and man: find a command by a word, and read its page, in the
+ * words every Unix hand already knows (builtins/helpSections.ts).
+ *
+ * @module
+ */
+import { envelope_ok, envelope_error } from '@fnndsc/menu';
+import { apropos_search } from '../helpSections.js';
+import { builtin_help, helpLookup_make } from '../help.js';
+/**
+ * `apropos <word>`: every command, section and Shell topic whose name,
+ * summary or description holds the word.
+ *
+ * @param args - The word (several words are one phrase).
+ * @returns The matches, or nothing appropriate (exit 1, as apropos does).
+ */
+export async function builtin_apropos(args) {
+    const word = args.join(' ').trim();
+    if (word === '')
+        return envelope_error('', undefined, 'apropos: a word to look for: apropos <word>\n');
+    const hits = apropos_search(word, helpLookup_make());
+    if (hits.length === 0) {
+        process.exitCode = 1;
+        return envelope_ok(`${word}: nothing appropriate.\n`);
+    }
+    return envelope_ok(`${hits.join('\n')}\n`);
+}
+/**
+ * `man <command|Section|topic>` is `help` for it; `man -k <word>` is apropos.
+ *
+ * @param args - The words after `man`.
+ * @returns The page, or the matches.
+ */
+export async function builtin_man(args) {
+    if (args[0] === '-k')
+        return builtin_apropos(args.slice(1));
+    if (args.length === 0)
+        return envelope_error('', undefined, 'man: what manual page do you want? man <command>, man <Section>, man -k <word>\n');
+    return builtin_help(args);
+}
+//# sourceMappingURL=apropos.js.map

package/dist/builtins/sys/apropos.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"apropos.js","sourceRoot":"","sources":["../../../src/builtins/sys/apropos.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAmB,WAAW,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC5E,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACpD,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAE3D;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,IAAc;IAClD,MAAM,IAAI,GAAW,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;IAC3C,IAAI,IAAI,KAAK,EAAE;QAAE,OAAO,cAAc,CAAC,EAAE,EAAE,SAAS,EAAE,+CAA+C,CAAC,CAAC;IACvG,MAAM,IAAI,GAAa,cAAc,CAAC,IAAI,EAAE,eAAe,EAAE,CAAC,CAAC;IAC/D,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACtB,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;QACrB,OAAO,WAAW,CAAC,GAAG,IAAI,0BAA0B,CAAC,CAAC;IACxD,CAAC;IACD,OAAO,WAAW,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC7C,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,IAAc;IAC9C,IAAI,IAAI,CAAC,CAAC,CAAC,KAAK,IAAI;QAAE,OAAO,eAAe,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IAC5D,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,cAAc,CAAC,EAAE,EAAE,SAAS,EAAE,kFAAkF,CAAC,CAAC;IAChJ,OAAO,YAAY,CAAC,IAAI,CAAC,CAAC;AAC5B,CAAC"}