@lakutata/entrypoint 3.0.0-beta.0

package/dist/esm/adapter/commander/CommanderCLIEntrypoint.js

@@ -0,0 +1,433 @@
+import { Command, CommanderError, InvalidArgumentError, Option } from 'commander';
+import { createReadStream } from 'node:fs';
+import path from 'node:path';
+import { applicationOf } from '../../lib/ApplicationOf.js';
+import { CLIContext } from '../../context/CLIContext.js';
+import { CLIChannel } from '../../channel/BuiltinChannels.js';
+import { EventsResult, FileResult, StatusResult } from '../../lib/Result.js';
+import { loadPrompts, prompt } from './Prompt.js';
+import { boxWrap, displayWidth } from './Width.js';
+/**
+ * The English texts, their arguments filled
+ * @param text
+ */
+function english(text) {
+    return text.text.replace(/\{(\w+)\}/g, (all, name) => text.params?.[name] ?? all);
+}
+/**
+ * The keys of the titles of the help of commander
+ */
+const TITLES = {
+    'Usage:': 'help.usage',
+    'Arguments:': 'help.arguments',
+    'Options:': 'help.options',
+    'Commands:': 'help.commands',
+    'Global Options:': 'help.globalOptions'
+};
+/**
+ * The type of a property, without null
+ * @param schema
+ */
+function typeOf(schema) {
+    const types = [].concat(schema.type ?? []).filter((type) => type !== 'null');
+    if (types.length)
+        return types[0];
+    if (schema.enum?.length)
+        return typeof schema.enum[0];
+    return undefined;
+}
+/**
+ * The kebab case of a property name (deviceId → device-id)
+ * @param name
+ */
+function kebabCase(name) {
+    return name.replace(/([a-z0-9])([A-Z])/g, '$1-$2').replace(/_/g, '-').toLowerCase();
+}
+/**
+ * Parse a value of an option by its schema
+ * @param schema
+ * @param value
+ */
+function parseValue(schema, value) {
+    let parsed;
+    switch (typeOf(schema)) {
+        case 'integer':
+        case 'number': {
+            parsed = Number(value);
+            if (value.trim() === '' || Number.isNaN(parsed))
+                throw new InvalidArgumentError('Not a number.');
+            break;
+        }
+        case 'boolean': {
+            if (!['true', 'false'].includes(value))
+                throw new InvalidArgumentError('Not a boolean.');
+            parsed = value === 'true';
+            break;
+        }
+        case 'object': {
+            try {
+                parsed = JSON.parse(value);
+            }
+            catch {
+                throw new InvalidArgumentError('Not a JSON object.');
+            }
+            break;
+        }
+        default:
+            parsed = value;
+    }
+    if (schema.enum && !schema.enum.includes(parsed))
+        throw new InvalidArgumentError(`Allowed choices are ${schema.enum.map((choice) => JSON.stringify(choice)).join(', ')}.`);
+    return parsed;
+}
+/**
+ * The option of a property
+ * @param property
+ * @param schema
+ * @param mandatory
+ * @param say the text of the help in the language of the user
+ * @param command the name of the command
+ */
+function propertyOption(property, schema, mandatory, say, command) {
+    const flag = `--${kebabCase(property)}`;
+    //A boolean or a value (DTO.Alternatives(DTO.Boolean(), …)): a flag taking an optional value
+    const alternatives = Array.isArray(schema.anyOf) ? schema.anyOf : [];
+    const valued = alternatives.some((alternative) => typeOf(alternative) === 'boolean')
+        ? alternatives.find((alternative) => typeOf(alternative) !== 'boolean')
+        : undefined;
+    const hints = [];
+    const choices = schema.enum ?? schema.items?.enum ?? valued?.enum;
+    if (choices)
+        hints.push(say('help.choices', 'choices: {choices}', { choices: choices.map((choice) => JSON.stringify(choice)).join(', ') }));
+    if (schema.default !== undefined)
+        hints.push(say('help.default', 'default: {value}', { value: JSON.stringify(schema.default) }));
+    const text = schema.description ? say(`commands.${command}.options.${property}`, schema.description) : '';
+    //The hints after the description, " (default: 1)"
+    const description = hints.length ? `${text}${say('help.hints', ' ({hints})', { hints: hints.join(say('help.separator', ', ')) })}`.trim() : text;
+    //--flag gives true, --flag <value> the value
+    if (valued)
+        return [new Option(`${flag} [value]`, description).argParser((value) => parseValue(valued, value))];
+    const type = typeOf(schema);
+    if (type === 'boolean') {
+        const options = [new Option(flag, description)];
+        //A flag on by default is turned off by its negation
+        if (schema.default === true)
+            options.push(new Option(`--no-${kebabCase(property)}`, say('help.negate', 'Turn off {flag}', { flag: flag })));
+        return options;
+    }
+    const option = type === 'array'
+        ? new Option(`${flag} <values...>`, description).argParser((value, previous) => [...(Array.isArray(previous) ? previous : []), parseValue(schema.items ?? {}, value)])
+        : new Option(`${flag} <${type === 'object' ? 'json' : 'value'}>`, description).argParser((value) => parseValue(schema, value));
+    return [option.makeOptionMandatory(mandatory)];
+}
+/**
+ * The default format of a result
+ * @param result
+ */
+function defaultFormat(result) {
+    if (result === undefined || result === null)
+        return undefined;
+    if (typeof result === 'string')
+        return result.endsWith('\n') ? result : `${result}\n`;
+    if (result instanceof Uint8Array)
+        return result;
+    return `${JSON.stringify(result, (key, value) => typeof value === 'bigint' ? value.toString() : value, 2)}\n`;
+}
+/**
+ * The message of an error
+ * @param error
+ */
+function errorMessage(error) {
+    if (error && typeof error === 'object') {
+        const { errMsg, message } = error;
+        if (typeof errMsg === 'string' && errMsg)
+            return errMsg;
+        if (typeof message === 'string' && message)
+            return message;
+    }
+    return String(error);
+}
+/**
+ * Create the CLI adapter of an entrypoint, parsing the command-line arguments with commander: each CLI action
+ * (`@CLIAction`) becomes a command, and the properties of its input DTO become its options. It needs the optional peer
+ * dependency `commander` (and `@inquirer/prompts` for the interactive prompts).
+ *
+ * A property becomes a kebab-case option (`deviceId` → `--device-id <value>`), parsed by its type: a number, `true` or
+ * `false`, a JSON object, an array (`--tags <values...>`), a boolean as a flag (with a `--no-<name>` negation when it
+ * defaults to `true`); the enums, the defaults and the descriptions appear in the help. The command text may declare
+ * positional arguments, given to the properties of their names (`'copy <files...> [target]'`), and its leading words
+ * before the last one name its groups (`'package exe <file>'` is the command `exe` of the group `package`).
+ *
+ * The command runs once the application has launched (all its objects, its bootstrap and the other adapters are
+ * ready). Its result is written to stdout (see `format`; an `EventsResult` writes each event's data, a `FileResult`
+ * the file's bytes); a failure writes `error: <message>` to stderr and ends with the code 1. Then the application exits
+ * with the command's code (see `exit`). When the entrypoint stops first, a command not started yet does not run, and
+ * the prompts and the event streams end.
+ * @param options The adapter options; by default it parses `process.argv`, prompts in a terminal, and exits the
+ * application once the command ended.
+ * @returns The adapter, to give to the `cli` option of `buildEntrypoints`.
+ * @example
+ * ```typescript
+ * import {Application, DTO} from 'lakutata'
+ * import {buildEntrypoints, Controller} from 'lakutata/com/entrypoint'
+ * import {CLIAction} from 'lakutata/decorator/ctrl'
+ * import {Expect} from 'lakutata/decorator/dto'
+ * import {commanderCLIEntrypoint} from 'lakutata/adapter/commander'
+ *
+ * class GreetDTO extends DTO {
+ *     @Expect(DTO.String().required().description('The name to greet'))
+ *     public name!: string
+ *
+ *     @Expect(DTO.Number().integer().optional().default(1).description('How many times'))
+ *     public times?: number
+ *
+ *     @Expect(DTO.Boolean().optional().default(false))
+ *     public loud?: boolean
+ * }
+ *
+ * class GreetController extends Controller {
+ *     //tool greet Ada --times 2 --loud
+ *     @CLIAction('greet <name>', GreetDTO)
+ *     public async greet(input: GreetDTO): Promise<string> {
+ *         const text: string = `Hello, ${input.name}`
+ *         return (input.loud ? text.toUpperCase() : text).repeat(input.times ?? 1)
+ *     }
+ * }
+ *
+ * Application.run({
+ *     id: 'tool.app',
+ *     name: 'Tool',
+ *     components: {
+ *         entrypoint: buildEntrypoints({
+ *             controllers: [GreetController],
+ *             cli: commanderCLIEntrypoint({bin: 'tool', description: 'A greeting tool', version: '1.0.0'})
+ *         })
+ *     }
+ * })
+ * ```
+ */
+export function commanderCLIEntrypoint(options = {}) {
+    const stdout = options.stdout ?? process.stdout;
+    const stderr = options.stderr ?? process.stderr;
+    const stdin = options.stdin ?? process.stdin;
+    const format = options.format ?? defaultFormat;
+    //Aborts the prompts and the event streams when the adapter stops
+    const stopController = new AbortController();
+    const write = (output) => {
+        if (output !== undefined && output.length)
+            stdout.write(output);
+    };
+    /**
+     * Write the result of an action
+     * @param result
+     */
+    const output = async (result) => {
+        if (result instanceof EventsResult) {
+            return await result.producer((data) => {
+                if (!stopController.signal.aborted)
+                    write(format(data));
+            }, stopController.signal);
+        }
+        if (result instanceof FileResult) {
+            const source = result.source;
+            if (Buffer.isBuffer(source))
+                return write(source);
+            const stream = typeof source === 'string' ? createReadStream(path.resolve(source)) : source;
+            return await new Promise((resolve, reject) => {
+                stream.once('error', reject).once('end', resolve).pipe(stdout, { end: false });
+            });
+        }
+        write(format(result instanceof StatusResult ? result.data : result));
+    };
+    /**
+     * Whether the missing options are prompted: the prompts installed (else the parser requires the options)
+     */
+    const interactive = async () => {
+        if (options.interactive === false)
+            return false;
+        if (options.interactive !== true && !(stdin.isTTY && stdout.isTTY))
+            return false;
+        return !!(await loadPrompts());
+    };
+    /**
+     * Run a command
+     * @param runtime
+     * @param action
+     * @param data
+     * @param prompting
+     * @param describe the description of a property in the language of the user
+     * @param say the text of the prompts in the language of the user
+     */
+    const execute = async (runtime, action, data, prompting, describe, say) => {
+        try {
+            if (prompting)
+                await prompt(action, data, { input: stdin, output: stdout, signal: stopController.signal }, describe, say);
+            const context = new CLIContext({ command: action.address.command, data: data });
+            await output(await runtime.dispatchTo(action, context));
+            return 0;
+        }
+        catch (error) {
+            stderr.write(`error: ${errorMessage(error)}\n`);
+            return 1;
+        }
+    };
+    /**
+     * Parse the arguments and run the command
+     * @param runtime
+     */
+    const run = async (runtime) => {
+        const argv = options.argv ?? process.argv.slice(2);
+        if (!argv.length && options.noCommand === 'ignore')
+            return undefined;
+        const prompting = await interactive();
+        //The texts of the help and of the prompts in the language of the user
+        const translate = options.translate ? await options.translate(runtime.module) : english;
+        const say = (key, text, params) => translate({ key: key, text: text, params: params });
+        const program = new Command(options.bin ?? path.basename(process.argv[1] ?? 'cli', path.extname(process.argv[1] ?? '')))
+            .exitOverride()
+            .configureOutput({
+            writeOut: (text) => stdout.write(text),
+            writeErr: (text) => stderr.write(text)
+        });
+        if (options.translate) {
+            //Inherited by the commands created next
+            program
+                .configureHelp({
+                styleTitle: (title) => TITLES[title] ? say(TITLES[title], title) : title,
+                //The widths of the wide characters (Chinese, Japanese, Korean), their lines wrapped between them
+                displayWidth: displayWidth,
+                boxWrap: (text, width) => boxWrap(text, width)
+            })
+                .helpOption('-h, --help', say('help.helpOption', 'display help for command'));
+            if (runtime.actions.length)
+                program.helpCommand('help [command]', say('help.helpCommand', 'display help for command'));
+        }
+        if (options.description)
+            program.description(say('description', options.description));
+        /**
+         * A group of commands, its help listing them
+         * @param parent
+         * @param group its name
+         * @param names the names of its groups and its own
+         */
+        const commandGroup = (parent, group, names) => {
+            const created = parent.command(group);
+            const description = options.groups?.[names.join(' ')];
+            if (description)
+                created.description(say(`commands.${names.join('.')}.description`, description));
+            if (options.translate)
+                created.helpCommand('help [command]', say('help.helpCommand', 'display help for command'));
+            return created;
+        };
+        if (options.version)
+            program.version(options.version, '-V, --version', say('help.versionOption', 'output the version number'));
+        let code = 0;
+        for (const action of runtime.actions) {
+            const schema = action.jsonSchema;
+            const required = new Set(schema.required ?? []);
+            //The command may declare positional arguments ("run <script>", "copy <files...> [target]"), given to the properties of their names;
+            //its words before them but the last are its groups ("package exe <file>": the command exe of the group package)
+            const words = action.address.command.trim().split(/\s+/);
+            const first = words.findIndex((word) => /^[<[]/.test(word));
+            const names = first < 0 ? words : words.slice(0, first);
+            let parent = program;
+            names.slice(0, -1).forEach((group, index) => {
+                parent = parent.commands.find((existing) => existing.name() === group) ?? commandGroup(parent, group, names.slice(0, index + 1));
+            });
+            const command = parent.command([names.at(-1), ...words.slice(names.length)].join(' ')).allowExcessArguments(false);
+            //The key of its texts: the names of its groups and its own
+            const name = names.join('.');
+            command.description(action.description ? say(`commands.${name}.description`, action.description) : action.name);
+            const positional = command.registeredArguments.map((argument) => argument.name());
+            //The description of a property: the one of its argument or of its option
+            const describe = (property) => {
+                const text = schema.properties?.[property]?.description;
+                return text ? say(`commands.${name}.${positional.includes(property) ? 'arguments' : 'options'}.${property}`, text) : undefined;
+            };
+            for (const argument of command.registeredArguments) {
+                const propertySchema = schema.properties?.[argument.name()];
+                if (!propertySchema)
+                    continue;
+                if (propertySchema.description)
+                    argument.description = describe(argument.name());
+                if (argument.variadic) {
+                    argument.argParser((value, previous) => [...(Array.isArray(previous) ? previous : []), parseValue(propertySchema.items ?? {}, value)]);
+                }
+                else {
+                    argument.argParser((value) => parseValue(propertySchema, value));
+                }
+            }
+            //The properties by the attribute names of their options
+            const properties = new Map();
+            for (const [property, propertySchema] of Object.entries(schema.properties ?? {})) {
+                if (positional.includes(property))
+                    continue;
+                const mandatory = !prompting && required.has(property) && propertySchema.default === undefined;
+                for (const option of propertyOption(property, propertySchema, mandatory, say, name)) {
+                    command.addOption(option);
+                    properties.set(option.attributeName(), property);
+                }
+            }
+            command.action(async () => {
+                const data = {};
+                positional.forEach((name, index) => {
+                    const value = command.processedArgs[index];
+                    if (value !== undefined)
+                        data[name] = value;
+                });
+                for (const [attribute, value] of Object.entries(command.opts())) {
+                    if (value !== undefined && properties.has(attribute))
+                        data[properties.get(attribute)] = value;
+                }
+                code = await execute(runtime, action, data, prompting, describe, say);
+            });
+        }
+        await options.configure?.(program);
+        try {
+            await program.parseAsync(argv, { from: 'user' });
+        }
+        catch (error) {
+            if (error instanceof CommanderError)
+                return error.exitCode;
+            throw error;
+        }
+        return code;
+    };
+    /**
+     * End with the code of the command
+     * @param runtime
+     * @param code
+     */
+    const exit = async (runtime, code) => {
+        const mode = options.exit ?? 'application';
+        if (typeof mode === 'function')
+            return await mode(code);
+        if (mode === 'none')
+            return;
+        const application = mode === 'application' ? applicationOf(runtime.module) : undefined;
+        if (application)
+            return application.exit(code);
+        process.exitCode = code;
+    };
+    return {
+        channel: 'cli',
+        definition: CLIChannel,
+        name: options.name,
+        middlewares: options.middlewares,
+        start: (runtime) => {
+            //The command runs once the application launched: every object, the bootstrap and the other adapters are ready
+            runtime.ready
+                .then(() => stopController.signal.aborted ? undefined : run(runtime))
+                .catch((error) => {
+                stderr.write(`error: ${errorMessage(error)}\n`);
+                return 1;
+            })
+                .then((code) => code === undefined || stopController.signal.aborted ? undefined : exit(runtime, code))
+                .catch((error) => stderr.write(`error: ${errorMessage(error)}\n`));
+        },
+        stop: () => {
+            //A command not started yet is not run, the prompts and the event streams are ended
+            stopController.abort();
+        }
+    };
+}

package/dist/esm/adapter/commander/Prompt.js

@@ -0,0 +1,127 @@
+import { PassThrough } from 'node:stream';
+import { DTO } from '@lakutata/core';
+/**
+ * The property names of the secrets, prompted without echo
+ */
+const SECRET = /pass(word)?|secret|token|api[-_]?key|credential/i;
+/**
+ * The prompts, undefined when @inquirer/prompts is not installed
+ */
+let prompts;
+/**
+ * Load the prompts
+ */
+export function loadPrompts() {
+    prompts ??= import('@inquirer/prompts').catch(() => undefined);
+    return prompts;
+}
+/**
+ * The type of a property, without null
+ * @param schema
+ */
+function typeOf(schema) {
+    const types = [].concat(schema.type ?? []).filter((type) => type !== 'null');
+    if (types.length)
+        return types[0];
+    if (schema.enum?.length)
+        return typeof schema.enum[0];
+    return undefined;
+}
+/**
+ * Validate an answer by the rules of its property in the DTO of the action
+ * @param dto
+ * @param property
+ */
+function validator(dto, property) {
+    let field;
+    try {
+        field = dto.Schema().extract(property).label(property);
+    }
+    catch {
+        //A property without its own rule is validated with the whole input
+        return async () => true;
+    }
+    return async (value) => {
+        try {
+            await DTO.validateAsync(value, field);
+            return true;
+        }
+        catch (error) {
+            return error.errMsg ?? error.message;
+        }
+    };
+}
+/**
+ * Prompt for the required properties missing from the input of an action, when @inquirer/prompts is installed
+ * @param action
+ * @param data
+ * @param streams
+ * @param describe the description of a property in the language of the user
+ * @param say the text of the prompts in the language of the user
+ */
+export async function prompt(action, data, streams, describe = (property) => action.jsonSchema.properties?.[property]?.description, say = (key, text) => text) {
+    const schema = action.jsonSchema;
+    const missing = (schema.required ?? []).filter((property) => data[property] === undefined && schema.properties?.[property]?.default === undefined);
+    if (!missing.length)
+        return;
+    const inquirer = await loadPrompts();
+    if (!inquirer)
+        return;
+    for (const property of missing) {
+        //A prompt ends its output once answered, the output of the adapter is kept open
+        const output = new PassThrough();
+        output.pipe(streams.output, { end: false });
+        try {
+            data[property] = await ask(inquirer, action, property, schema.properties?.[property] ?? {}, { input: streams.input, output: output, signal: streams.signal }, describe(property), say);
+        }
+        finally {
+            output.unpipe(streams.output);
+        }
+    }
+}
+/**
+ * Ask for a property
+ * @param inquirer
+ * @param action
+ * @param property
+ * @param propertySchema
+ * @param context
+ * @param description the description of the property in the language of the user
+ * @param say the text of the prompts in the language of the user
+ */
+async function ask(inquirer, action, property, propertySchema, context, description, say) {
+    const message = description ? `${description} (${property})` : property;
+    const validate = validator(action.dto, property);
+    const type = typeOf(propertySchema);
+    const choices = (values) => values.map((value) => ({ name: String(value), value: value }));
+    if (type === 'boolean')
+        return await inquirer.confirm({ message: message }, context);
+    if (propertySchema.enum)
+        return await inquirer.select({ message: message, choices: choices(propertySchema.enum) }, context);
+    if (type === 'array' && propertySchema.items?.enum)
+        return await inquirer.checkbox({ message: message, choices: choices(propertySchema.items.enum), validate: (selected) => validate(selected.map((choice) => choice.value)) }, context);
+    if (type === 'number' || type === 'integer')
+        return await inquirer.number({ message: message, required: true, step: type === 'integer' ? 1 : 'any', validate: validate }, context);
+    if (type === 'string' && (propertySchema.format === 'password' || SECRET.test(property)))
+        return await inquirer.password({ message: message, mask: '*', validate: validate }, context);
+    //The arrays are separated by commas, the objects are written in JSON
+    const parse = (answer) => {
+        if (type === 'array')
+            return answer.split(',').map((item) => item.trim()).filter((item) => !!item);
+        if (type === 'object')
+            return JSON.parse(answer);
+        return answer;
+    };
+    return parse(await inquirer.input({
+        message: message,
+        required: true,
+        validate: async (value) => {
+            try {
+                return await validate(parse(value));
+            }
+            catch {
+                return say('prompt.json', 'Not a JSON object');
+            }
+        }
+    }, context));
+}

package/dist/esm/adapter/commander/Width.js

@@ -0,0 +1,63 @@
+import { stripVTControlCharacters } from 'node:util';
+/**
+ * The wide characters of the terminals: the Chinese, Japanese and Korean ones, the full width forms
+ */
+const WIDE = '\\u1100-\\u115F\\u2E80-\\u303E\\u3041-\\u33FF\\u3400-\\u4DBF\\u4E00-\\u9FFF\\uA000-\\uA4CF\\uAC00-\\uD7A3\\uF900-\\uFAFF\\uFE30-\\uFE4F\\uFF00-\\uFF60\\uFFE0-\\uFFE6\\u{20000}-\\u{3FFFD}';
+/**
+ * The punctuation which does not start a line
+ */
+const CLOSING = '、。，．：；！？）」』】〕〉》％,.:;!?)\\]}';
+/**
+ * The punctuation which does not end a line
+ */
+const OPENING = '（「『【〔〈《(\\[{';
+const WIDE_CHARACTER = new RegExp(`[${WIDE}]`, 'u');
+/**
+ * The chunks of a line the wrapping keeps whole: a word, or a wide character, with the punctuation opening and
+ * closing it
+ */
+const CHUNK = new RegExp(`\\s*[${OPENING}]*(?:[${WIDE}]|[^\\s${WIDE}]+)[${CLOSING}]*`, 'gu');
+/**
+ * The width of a text in a terminal, the wide characters taking two columns
+ * @param text
+ */
+export function displayWidth(text) {
+    let width = 0;
+    for (const character of stripVTControlCharacters(text))
+        width += WIDE_CHARACTER.test(character) ? 2 : 1;
+    return width;
+}
+/**
+ * Wrap a text to a width, as commander does, the lines of wide characters wrapped between them
+ * @param text
+ * @param width
+ * @param minimum the width under which the text is not wrapped
+ */
+export function boxWrap(text, width, minimum = 40) {
+    if (width < minimum)
+        return text;
+    const wrapped = [];
+    for (const line of text.split(/\r\n|\n/)) {
+        const chunks = line.match(CHUNK);
+        if (!chunks) {
+            wrapped.push('');
+            continue;
+        }
+        let current = chunks.shift();
+        let currentWidth = displayWidth(current);
+        for (const chunk of chunks) {
+            const chunkWidth = displayWidth(chunk);
+            if (currentWidth + chunkWidth <= width) {
+                current += chunk;
+                currentWidth += chunkWidth;
+                continue;
+            }
+            wrapped.push(current);
+            //The space at the break removed
+            current = chunk.trimStart();
+            currentWidth = displayWidth(current);
+        }
+        wrapped.push(current);
+    }
+    return wrapped.join('\n');
+}