@futdevpro/nts-dynamo 1.15.307 → 1.15.309

package/build/_modules/cli/_services/cli-program.control-service.js

@@ -0,0 +1,271 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DyCLI_Program_ControlService = void 0;
+const crypto_1 = require("crypto");
+const fsm_dynamo_1 = require("@futdevpro/fsm-dynamo");
+const global_settings_const_1 = require("../../../_collections/global-settings.const");
+const cli_commander_util_1 = require("../_collections/cli-commander.util");
+const cli_envelope_util_1 = require("../_collections/cli-envelope.util");
+const cli_flag_util_1 = require("../_collections/cli-flag.util");
+const cli_exit_code_type_enum_1 = require("../_enums/cli-exit-code.type-enum");
+const cli_output_type_enum_1 = require("../_enums/cli-output.type-enum");
+const cli_command_params_control_model_1 = require("../_models/control-models/cli-command-params.control-model");
+/** The common options of every command. */
+const DyCLI_outputOptions = ['json', 'pretty', 'dry-run'];
+/** The common options of a command that calls a server operation. */
+const DyCLI_remoteOptions = ['api-key', 'base-url', 'timeout'];
+/**
+ * The commander program of a Dynamo CLI (HP-DOPL MP-4.3 + MP-4.4): the skeleton the fleet CLIs repeat by hand
+ * (`name / description / version / addHelpText / parse`), the common options, and ONE execution path per command —
+ * `before` → own `action` or the server call → `after` → the `fo` result envelope and the exit code.
+ *
+ * - Success: the envelope on stdout (or the `formatHuman` text when the command's output is `human` and no `--json`).
+ * - Failure: the envelope on stderr (or `<command>: <code>: <message>`), exit code by `DyCLI_Command_Params.exitCodeOf`.
+ * - An argument error (unknown option, invalid value, missing required flag): the `cli.parse` envelope, exit `usage`;
+ *   `--help` / `--version` exit 0.
+ * - `run()` RETURNS the exit code and never calls `process.exit` — `process.exitCode = await program.run()`.
+ *
+ * `build()` gives the commander program before parsing, so `registerDynamoCommands(program, version)` of
+ * `@futdevpro/cli-dynamo` can still be called on it (or pass it as `configure`).
+ *
+ * @example
+ * ```ts
+ * const cli: DyCLI_Program_ControlService = new DyCLI_Program_ControlService({
+ *   name: 'fo', description: 'Organizer CLI', version: '2.0.0',
+ *   commands: [ listTasks, backup ],
+ *   callOperation: mcpCaller,                              // generated commands call the server through MCP
+ * });
+ *
+ * process.exitCode = await cli.run();
+ * ```
+ */
+class DyCLI_Program_ControlService {
+    /** The program name (the binary). */
+    name;
+    /** The program description. */
+    description;
+    /** The program version (`-v, --version`). */
+    version;
+    /** The commands. */
+    commands;
+    /** Extra help text after the command list. */
+    helpText;
+    /** The exit code of the last command run through this program. */
+    lastExitCode = 0;
+    callOperation;
+    configure;
+    settings;
+    io;
+    /**
+     * @param set - the program settings; throws a coded `DyFM_Error` (500 `DyNTS-CLI-*`) when invalid
+     */
+    constructor(set) {
+        const invalid = (code, reason) => new fsm_dynamo_1.DyFM_Error({
+            status: 500,
+            errorCode: `${global_settings_const_1.DyNTS_global_settings.systemShortCodeName}|${code}`,
+            message: `DyCLI_Program_ControlService construction failed: ${reason}`,
+        });
+        if (typeof set?.name !== 'string' || !/^[a-z][a-z0-9-]*$/.test(set.name)) {
+            throw invalid('DyNTS-CLI-NAM', `the program name must be kebab-case (got: ${JSON.stringify(set?.name)})`);
+        }
+        if (typeof set.description !== 'string' || !set.description.trim() || typeof set.version !== 'string' ||
+            !set.version.trim()) {
+            throw invalid('DyNTS-CLI-DSC', 'the program needs a description and a version');
+        }
+        if (!Array.isArray(set.commands) ||
+            set.commands.some((command) => !(command instanceof cli_command_params_control_model_1.DyCLI_Command_Params))) {
+            throw invalid('DyNTS-CLI-CMD', 'commands must be DyCLI_Command_Params instances');
+        }
+        const names = set.commands.flatMap((command) => [command.command, ...command.aliases]);
+        const duplicate = names.find((name, index) => names.indexOf(name) !== index);
+        if (duplicate) {
+            throw invalid('DyNTS-CLI-DUP', `two commands use the name "${duplicate}"`);
+        }
+        if (set.callOperation !== undefined && typeof set.callOperation !== 'function') {
+            throw invalid('DyNTS-CLI-CAL', 'callOperation must be a function');
+        }
+        this.name = set.name;
+        this.description = set.description;
+        this.version = set.version;
+        this.commands = [...set.commands];
+        this.helpText = set.helpText;
+        this.callOperation = set.callOperation;
+        this.configure = set.configure;
+        this.settings = set.settings === undefined ? global_settings_const_1.DyNTS_global_settings.cli_settings : set.settings;
+        this.io = set.io ?? {
+            stdout: (text) => {
+                process.stdout.write(text);
+            },
+            stderr: (text) => {
+                process.stderr.write(text);
+            },
+        };
+    }
+    /**
+     * Builds the commander program with every command and its common options; nothing is parsed yet.
+     * @throws 501 `DyNTS-OPT-MIS` when `commander` is not installed
+     */
+    async build() {
+        const commander = await cli_commander_util_1.DyCLI_Commander_Util.load();
+        const program = new commander.Command(this.name)
+            .description(this.description)
+            .version(this.version, '-v, --version', 'output the current version');
+        if (this.helpText) {
+            program.addHelpText('after', this.helpText);
+        }
+        this.commands.forEach((params) => {
+            const command = params.buildCommand(commander, async (values) => {
+                this.lastExitCode = await this.execute(params, values, DyCLI_Program_ControlService.commonOf(command.opts(), common));
+            });
+            const common = this.addCommonOptions(commander, params, command);
+            program.addCommand(command);
+        });
+        await this.configure?.(program);
+        return program;
+    }
+    /**
+     * Parses the command line and runs the command.
+     * @param argv - the full argv (default: `process.argv`)
+     * @returns the exit code — set it as `process.exitCode`
+     */
+    async run(argv = process.argv) {
+        const program = await this.build();
+        let parseMessage = '';
+        // commander must not exit the process: every command gets the override, and its messages are captured
+        [program, ...program.commands].forEach((command) => {
+            command.exitOverride().configureOutput({
+                writeOut: (text) => this.io.stdout(text),
+                writeErr: (text) => {
+                    parseMessage += text;
+                },
+            });
+        });
+        this.lastExitCode = 0;
+        try {
+            await program.parseAsync(argv);
+            return this.lastExitCode;
+        }
+        catch (error) {
+            const failure = error;
+            // help and version are not errors
+            if (failure?.code === 'commander.helpDisplayed' || failure?.code === 'commander.version' ||
+                failure?.code === 'commander.help') {
+                return 0;
+            }
+            if (typeof failure?.code !== 'string' || !failure.code.startsWith('commander.')) {
+                throw error;
+            }
+            const envelope = cli_envelope_util_1.DyCLI_Envelope_Util.failure({
+                action: 'cli.parse', requestId: (0, crypto_1.randomUUID)(), startedAt: Date.now(),
+                error: { code: 'INVALID_ARGS', message: (failure.message || parseMessage).replace(/^error:\s*/i, '').trim() },
+            });
+            this.io.stderr(cli_envelope_util_1.DyCLI_Envelope_Util.stringify(envelope, argv.includes('--pretty')));
+            return this.exitCodeOfParse();
+        }
+    }
+    /**
+     * Runs one command: `before` → `action` or the server call → `after`, then writes the envelope.
+     * @param params - the command
+     * @param values - the collected flag values
+     * @param common - the common options
+     * @returns the exit code
+     */
+    async execute(params, values, common) {
+        const startedAt = Date.now();
+        const requestId = (0, crypto_1.randomUUID)();
+        const human = !common.json && params.getOutput(this.settings) === cli_output_type_enum_1.DyCLI_Output_Type.human;
+        try {
+            await params.before?.(values, params);
+            const result = params.action ?
+                await params.action(values, params, common) : await this.callServer(params, values, common);
+            await params.after?.(result, values, params);
+            if (human) {
+                this.io.stdout(`${params.formatHuman ? params.formatHuman(result) : JSON.stringify(result, null, 2)}\n`);
+            }
+            else {
+                this.io.stdout(cli_envelope_util_1.DyCLI_Envelope_Util.stringify(cli_envelope_util_1.DyCLI_Envelope_Util.success({ action: params.command, requestId: requestId, startedAt: startedAt, result: result }), common.pretty));
+            }
+            return 0;
+        }
+        catch (error) {
+            const envelope = cli_envelope_util_1.DyCLI_Envelope_Util.failure({
+                action: params.command, requestId: requestId, startedAt: startedAt, error: error,
+            });
+            if (human) {
+                this.io.stderr([
+                    `${params.command}: ${envelope.error.code}: ${envelope.error.message}`,
+                    ...(envelope.error.nextStep ? [`next: ${envelope.error.nextStep}`] : []),
+                ].join('\n') + '\n');
+            }
+            else {
+                this.io.stderr(cli_envelope_util_1.DyCLI_Envelope_Util.stringify(envelope, common.pretty));
+            }
+            return params.exitCodeOf(error, this.settings);
+        }
+    }
+    /** Calls the operation of a generated command through the configured caller. */
+    async callServer(params, values, common) {
+        if (!this.callOperation) {
+            throw new fsm_dynamo_1.DyFM_Error({
+                status: 501,
+                errorCode: `${global_settings_const_1.DyNTS_global_settings.systemShortCodeName}|DyNTS-CLI-NOC`,
+                message: `command "${params.command}" calls a server operation, but the program has no callOperation`,
+                userMessage: `This CLI can not call "${params.command}": no server connection is configured.`,
+            });
+        }
+        return this.callOperation(params, values, common);
+    }
+    /**
+     * Adds the common options a command does not already have (a command flag of the same name wins).
+     * @returns the added long flags
+     */
+    addCommonOptions(commander, params, command) {
+        const own = params.flags.map((flag) => flag.flag);
+        const wanted = params.operation ? [...DyCLI_outputOptions, ...DyCLI_remoteOptions] : DyCLI_outputOptions;
+        const options = {
+            'json': () => new commander.Option('--json', 'print the JSON result envelope'),
+            'pretty': () => new commander.Option('--pretty', 'indent the JSON output'),
+            'dry-run': () => new commander.Option('--dry-run', 'validate and preview without saving'),
+            'api-key': () => new commander.Option('--api-key <key>', 'the API key of the server call'),
+            'base-url': () => new commander.Option('--base-url <url>', 'the server base URL'),
+            'timeout': () => new commander.Option('--timeout <ms>', 'the server call timeout in milliseconds')
+                .argParser((raw) => {
+                if (!/^\d+$/.test(raw.trim()) || Number(raw) < 1) {
+                    throw new commander.InvalidArgumentError('--timeout must be a positive integer of milliseconds');
+                }
+                return Number(raw);
+            }),
+        };
+        const added = wanted.filter((flag) => !own.includes(flag) && !cli_flag_util_1.DyCLI_reservedFlags.includes(flag));
+        added.forEach((flag) => {
+            command.addOption(options[flag]());
+        });
+        return added;
+    }
+    /** The exit code of a commander argument error: the `usage` code of the settings (a command override does not apply). */
+    exitCodeOfParse() {
+        return this.settings?.exitCodes?.usage ?? cli_exit_code_type_enum_1.DyCLI_ExitCode_Type.usage;
+    }
+    /**
+     * The common options from the parsed commander options — only the ones the program added to this command, so a
+     * command's own flag of the same name (e.g. the `dryRun` guardrail argument) stays a value, not a common option.
+     * @param options - the parsed options (`command.opts()`)
+     * @param added - the long flags of the common options added to the command
+     */
+    static commonOf(options, added) {
+        const common = {};
+        const keys = {
+            'json': 'json', 'pretty': 'pretty', 'dry-run': 'dryRun', 'api-key': 'apiKey', 'base-url': 'baseUrl',
+            'timeout': 'timeoutMs',
+        };
+        added.forEach((flag) => {
+            const value = options?.[cli_flag_util_1.DyCLI_Flag_Util.attributeOf(flag)];
+            if (value !== undefined) {
+                common[keys[flag]] = value;
+            }
+        });
+        return common;
+    }
+}
+exports.DyCLI_Program_ControlService = DyCLI_Program_ControlService;
+//# sourceMappingURL=cli-program.control-service.js.map

package/build/_modules/cli/_services/cli-program.control-service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-program.control-service.js","sourceRoot":"","sources":["../../../../src/_modules/cli/_services/cli-program.control-service.ts"],"names":[],"mappings":"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"}

package/build/_modules/cli/index.d.ts

@@ -1,9 +1,14 @@
 export * from './_enums/cli-exit-code.type-enum';
 export * from './_enums/cli-flag-value.type-enum';
 export * from './_enums/cli-output.type-enum';
+export * from './_models/interfaces/cli-common-options.interface';
+export * from './_models/interfaces/cli-envelope.interface';
 export * from './_models/interfaces/cli-flag.interface';
 export * from './_models/interfaces/cli-settings.interface';
 export * from './_models/control-models/cli-command-params.control-model';
 export * from './_collections/cli-commander.util';
+export * from './_collections/cli-envelope.util';
 export * from './_collections/cli-flag.util';
+export * from './_collections/cli-mcp-caller.util';
+export * from './_services/cli-program.control-service';
 //# sourceMappingURL=index.d.ts.map

package/build/_modules/cli/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/_modules/cli/index.ts"],"names":[],"mappings":"AAOA,cAAc,kCAAkC,CAAC;AACjD,cAAc,mCAAmC,CAAC;AAClD,cAAc,+BAA+B,CAAC;AAG9C,cAAc,yCAAyC,CAAC;AACxD,cAAc,6CAA6C,CAAC;AAG5D,cAAc,2DAA2D,CAAC;AAG1E,cAAc,mCAAmC,CAAC;AAClD,cAAc,8BAA8B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/_modules/cli/index.ts"],"names":[],"mappings":"AAOA,cAAc,kCAAkC,CAAC;AACjD,cAAc,mCAAmC,CAAC;AAClD,cAAc,+BAA+B,CAAC;AAG9C,cAAc,mDAAmD,CAAC;AAClE,cAAc,6CAA6C,CAAC;AAC5D,cAAc,yCAAyC,CAAC;AACxD,cAAc,6CAA6C,CAAC;AAG5D,cAAc,2DAA2D,CAAC;AAG1E,cAAc,mCAAmC,CAAC;AAClD,cAAc,kCAAkC,CAAC;AACjD,cAAc,8BAA8B,CAAC;AAC7C,cAAc,oCAAoC,CAAC;AAGnD,cAAc,yCAAyC,CAAC"}

package/build/_modules/cli/index.js

@@ -9,11 +9,17 @@ tslib_1.__exportStar(require("./_enums/cli-exit-code.type-enum"), exports);
 tslib_1.__exportStar(require("./_enums/cli-flag-value.type-enum"), exports);
 tslib_1.__exportStar(require("./_enums/cli-output.type-enum"), exports);
 // INTERFACES
+tslib_1.__exportStar(require("./_models/interfaces/cli-common-options.interface"), exports);
+tslib_1.__exportStar(require("./_models/interfaces/cli-envelope.interface"), exports);
 tslib_1.__exportStar(require("./_models/interfaces/cli-flag.interface"), exports);
 tslib_1.__exportStar(require("./_models/interfaces/cli-settings.interface"), exports);
 // CONTROL MODELS
 tslib_1.__exportStar(require("./_models/control-models/cli-command-params.control-model"), exports);
 // COLLECTIONS
 tslib_1.__exportStar(require("./_collections/cli-commander.util"), exports);
+tslib_1.__exportStar(require("./_collections/cli-envelope.util"), exports);
 tslib_1.__exportStar(require("./_collections/cli-flag.util"), exports);
+tslib_1.__exportStar(require("./_collections/cli-mcp-caller.util"), exports);
+// SERVICES
+tslib_1.__exportStar(require("./_services/cli-program.control-service"), exports);
 //# sourceMappingURL=index.js.map

package/build/_modules/cli/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/_modules/cli/index.ts"],"names":[],"mappings":";AAEA,qHAAqH;AACrH,qHAAqH;AACrH,8DAA8D;;;AAE9D,QAAQ;AACR,2EAAiD;AACjD,4EAAkD;AAClD,wEAA8C;AAE9C,aAAa;AACb,kFAAwD;AACxD,sFAA4D;AAE5D,iBAAiB;AACjB,oGAA0E;AAE1E,cAAc;AACd,4EAAkD;AAClD,uEAA6C"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/_modules/cli/index.ts"],"names":[],"mappings":";AAEA,qHAAqH;AACrH,qHAAqH;AACrH,8DAA8D;;;AAE9D,QAAQ;AACR,2EAAiD;AACjD,4EAAkD;AAClD,wEAA8C;AAE9C,aAAa;AACb,4FAAkE;AAClE,sFAA4D;AAC5D,kFAAwD;AACxD,sFAA4D;AAE5D,iBAAiB;AACjB,oGAA0E;AAE1E,cAAc;AACd,4EAAkD;AAClD,2EAAiD;AACjD,uEAA6C;AAC7C,6EAAmD;AAEnD,WAAW;AACX,kFAAwD"}

package/build/_modules/mcp/_collections/mcp-client.util.d.ts

@@ -0,0 +1,86 @@
+/** One MCP server call target. */
+export interface DyNTS_McpClient_Target {
+    /** The server base URL (e.g. `https://organizer.example.com/api`). */
+    baseUrl: string;
+    /** The MCP endpoint path under the base URL; default: `/mcp` (the `DyNTS_McpHttpEndpoint_Util` default). */
+    endpointPath?: string;
+    /** Sent as `Authorization: Bearer <apiKey>`. */
+    apiKey?: string;
+    /** Extra request headers. */
+    headers?: {
+        [name: string]: string;
+    };
+    /** The request timeout in milliseconds; default: 20 000 (the organizer `fo` client). */
+    timeoutMs?: number;
+}
+/** The outcome of a `tools/call`. */
+export interface DyNTS_McpClient_ToolResult {
+    /** The tool output: the first text block, parsed as JSON when it is JSON. */
+    data: unknown;
+    /** The non-fatal warnings of the call (the second `{ warnings }` block of a Dynamo MCP server). */
+    warnings: string[];
+}
+/** A tool as `tools/list` advertises it. */
+export interface DyNTS_McpClient_Tool {
+    /** The tool name. */
+    name: string;
+    /** The tool description. */
+    description?: string;
+    /** The JSON schema of the arguments. */
+    inputSchema?: {
+        [key: string]: unknown;
+    };
+}
+/**
+ * The standard MCP client (HP-DOPL MP-4.5, DMCP-015): `tools/list` and `tools/call` over Streamable HTTP with plain
+ * `fetch` — no SDK, so a CLI stays light. It replaces the hand-written JSON-RPC clients of the fleet (organizer `fo`,
+ * the CCAP probe) with one tested implementation.
+ *
+ * Every failure is a coded `DyFM_Error` with an HTTP-like status, so a CLI maps it to the right exit code:
+ * - the server answered non-2xx → that status (`DyNTS-MCC-HTP`);
+ * - a JSON-RPC error → `DyNTS_McpError_Util.statusOfCode` (`DyNTS-MCC-RPC`);
+ * - a tool error (`isError`) → the status of its code, its own `errorCode` and message kept;
+ * - the server could not be reached or timed out → no status, the network code kept on `error` (`DyNTS-MCC-NET`);
+ * - an unreadable answer → 502 (`DyNTS-MCC-RES`).
+ *
+ * @example
+ * ```ts
+ * const result: DyNTS_McpClient_ToolResult = await DyNTS_McpClient_Util.callTool({
+ *   baseUrl: 'https://organizer.example.com/api', apiKey: key, name: 'tasks.list', arguments: { projectId: 'p-1' },
+ * });
+ * ```
+ */
+export declare class DyNTS_McpClient_Util {
+    /**
+     * Lists the advertised tools.
+     * @param target - the server
+     */
+    static listTools(target: DyNTS_McpClient_Target): Promise<DyNTS_McpClient_Tool[]>;
+    /**
+     * Calls a tool.
+     * @param set - the server, the tool name and its arguments
+     * @throws a coded `DyFM_Error` — see the class description
+     */
+    static callTool(set: DyNTS_McpClient_Target & {
+        name: string;
+        arguments?: object;
+    }): Promise<DyNTS_McpClient_ToolResult>;
+    /**
+     * Sends one JSON-RPC request and returns its `result`.
+     * @param set - the server, the method and its params
+     * @throws a coded `DyFM_Error` — see the class description
+     */
+    static request(set: DyNTS_McpClient_Target & {
+        method: string;
+        params?: object;
+    }): Promise<unknown>;
+    /** The JSON-RPC message of an answer: a JSON body, or the last `data:` event of an SSE stream. */
+    private static parseBody;
+    /** A text parsed as JSON when it is JSON, else the text itself (`undefined` stays `undefined`). */
+    private static parseText;
+    /** The coded error of a tool error payload `{ ok: false, error: { code, message, errorCode } }`. */
+    private static toolError;
+    /** A coded client error. */
+    private static error;
+}
+//# sourceMappingURL=mcp-client.util.d.ts.map

package/build/_modules/mcp/_collections/mcp-client.util.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-client.util.d.ts","sourceRoot":"","sources":["../../../../src/_modules/mcp/_collections/mcp-client.util.ts"],"names":[],"mappings":"AAMA,kCAAkC;AAClC,MAAM,WAAW,sBAAsB;IACrC,sEAAsE;IACtE,OAAO,EAAE,MAAM,CAAC;IAChB,4GAA4G;IAC5G,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,gDAAgD;IAChD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,6BAA6B;IAC7B,OAAO,CAAC,EAAE;QAAE,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,CAAC;IACrC,wFAAwF;IACxF,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,qCAAqC;AACrC,MAAM,WAAW,0BAA0B;IACzC,6EAA6E;IAC7E,IAAI,EAAE,OAAO,CAAC;IACd,mGAAmG;IACnG,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,4CAA4C;AAC5C,MAAM,WAAW,oBAAoB;IACnC,qBAAqB;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,4BAA4B;IAC5B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,wCAAwC;IACxC,WAAW,CAAC,EAAE;QAAE,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,CAAC;CAC1C;AAKD;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,oBAAoB;IAC/B;;;OAGG;WACU,SAAS,CAAC,MAAM,EAAE,sBAAsB,GAAG,OAAO,CAAC,oBAAoB,EAAE,CAAC;IAWvF;;;;OAIG;WACU,QAAQ,CAAC,GAAG,EAAE,sBAAsB,GAAG;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,0BAA0B,CAAC;IAoB9H;;;;OAIG;WACU,OAAO,CAAC,GAAG,EAAE,sBAAsB,GAAG;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,OAAO,CAAC;IA2DzG,kGAAkG;IAClG,OAAO,CAAC,MAAM,CAAC,SAAS;IAcxB,mGAAmG;IACnG,OAAO,CAAC,MAAM,CAAC,SAAS;IAYxB,oGAAoG;IACpG,OAAO,CAAC,MAAM,CAAC,SAAS;IAexB,4BAA4B;IAC5B,OAAO,CAAC,MAAM,CAAC,KAAK;CAerB"}

package/build/_modules/mcp/_collections/mcp-client.util.js

@@ -0,0 +1,169 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DyNTS_McpClient_Util = void 0;
+const fsm_dynamo_1 = require("@futdevpro/fsm-dynamo");
+const global_settings_const_1 = require("../../../_collections/global-settings.const");
+const mcp_error_util_1 = require("./mcp-error.util");
+/** The JSON-RPC request id counter of the process. */
+let DyNTS_mcpClientRequestId = 0;
+/**
+ * The standard MCP client (HP-DOPL MP-4.5, DMCP-015): `tools/list` and `tools/call` over Streamable HTTP with plain
+ * `fetch` — no SDK, so a CLI stays light. It replaces the hand-written JSON-RPC clients of the fleet (organizer `fo`,
+ * the CCAP probe) with one tested implementation.
+ *
+ * Every failure is a coded `DyFM_Error` with an HTTP-like status, so a CLI maps it to the right exit code:
+ * - the server answered non-2xx → that status (`DyNTS-MCC-HTP`);
+ * - a JSON-RPC error → `DyNTS_McpError_Util.statusOfCode` (`DyNTS-MCC-RPC`);
+ * - a tool error (`isError`) → the status of its code, its own `errorCode` and message kept;
+ * - the server could not be reached or timed out → no status, the network code kept on `error` (`DyNTS-MCC-NET`);
+ * - an unreadable answer → 502 (`DyNTS-MCC-RES`).
+ *
+ * @example
+ * ```ts
+ * const result: DyNTS_McpClient_ToolResult = await DyNTS_McpClient_Util.callTool({
+ *   baseUrl: 'https://organizer.example.com/api', apiKey: key, name: 'tasks.list', arguments: { projectId: 'p-1' },
+ * });
+ * ```
+ */
+class DyNTS_McpClient_Util {
+    /**
+     * Lists the advertised tools.
+     * @param target - the server
+     */
+    static async listTools(target) {
+        const result = await DyNTS_McpClient_Util.request({ ...target, method: 'tools/list', params: {} });
+        if (!Array.isArray(result?.tools)) {
+            throw DyNTS_McpClient_Util.error({ code: 'DyNTS-MCC-RES', status: 502, message: 'tools/list answered without tools' });
+        }
+        return result.tools;
+    }
+    /**
+     * Calls a tool.
+     * @param set - the server, the tool name and its arguments
+     * @throws a coded `DyFM_Error` — see the class description
+     */
+    static async callTool(set) {
+        const result = await DyNTS_McpClient_Util.request({
+            ...set, method: 'tools/call', params: { name: set.name, arguments: set.arguments ?? {} },
+        });
+        const texts = (Array.isArray(result?.content) ? result.content : [])
+            .filter((block) => block?.type === 'text' && typeof block.text === 'string')
+            .map((block) => block.text);
+        const data = DyNTS_McpClient_Util.parseText(texts[0]);
+        if (result?.isError === true) {
+            throw DyNTS_McpClient_Util.toolError(set.name, data);
+        }
+        const second = DyNTS_McpClient_Util.parseText(texts[1]);
+        const warnings = Array.isArray(second?.warnings) ?
+            second.warnings.filter((warning) => typeof warning === 'string') : [];
+        return { data: data, warnings: warnings };
+    }
+    /**
+     * Sends one JSON-RPC request and returns its `result`.
+     * @param set - the server, the method and its params
+     * @throws a coded `DyFM_Error` — see the class description
+     */
+    static async request(set) {
+        const url = `${set.baseUrl?.replace(/\/+$/, '') ?? ''}${set.endpointPath ?? '/mcp'}`;
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), set.timeoutMs ?? 20000);
+        let response;
+        let text;
+        try {
+            response = await fetch(url, {
+                method: 'POST',
+                headers: {
+                    'content-type': 'application/json',
+                    // a Streamable HTTP server may answer with JSON or with an SSE stream
+                    'accept': 'application/json, text/event-stream',
+                    ...(set.apiKey ? { authorization: `Bearer ${set.apiKey}` } : {}),
+                    ...set.headers,
+                },
+                body: JSON.stringify({ jsonrpc: '2.0', id: ++DyNTS_mcpClientRequestId, method: set.method, params: set.params ?? {} }),
+                signal: controller.signal,
+            });
+            text = await response.text();
+        }
+        catch (error) {
+            const aborted = error?.name === 'AbortError';
+            const code = aborted ? 'ETIMEDOUT' : error?.cause?.code;
+            throw DyNTS_McpClient_Util.error({
+                code: 'DyNTS-MCC-NET',
+                message: aborted ? `the MCP server did not answer within ${set.timeoutMs ?? 20000} ms (${url})` :
+                    `the MCP server could not be reached (${url}${code ? `, ${code}` : ''})`,
+                cause: { code: code ?? 'ECONNREFUSED' },
+            });
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        const body = DyNTS_McpClient_Util.parseBody(text, response.headers.get('content-type'));
+        if (!response.ok) {
+            throw DyNTS_McpClient_Util.error({
+                code: 'DyNTS-MCC-HTP', status: response.status,
+                message: `the MCP server answered HTTP ${response.status}${body?.error?.message ? `: ${body.error.message}` : ''}`,
+            });
+        }
+        if (!body || typeof body !== 'object') {
+            throw DyNTS_McpClient_Util.error({ code: 'DyNTS-MCC-RES', status: 502, message: `unreadable MCP answer from ${url}` });
+        }
+        if (body.error) {
+            throw DyNTS_McpClient_Util.error({
+                code: 'DyNTS-MCC-RPC', status: mcp_error_util_1.DyNTS_McpError_Util.statusOfCode(body.error.code),
+                message: `${set.method}: ${body.error.message ?? 'JSON-RPC error'} (${body.error.code})`,
+            });
+        }
+        return body.result;
+    }
+    /** The JSON-RPC message of an answer: a JSON body, or the last `data:` event of an SSE stream. */
+    static parseBody(text, contentType) {
+        if (contentType?.includes('text/event-stream')) {
+            const events = text.split(/\r?\n/)
+                .filter((line) => line.startsWith('data:'))
+                .map((line) => line.slice(5).trim());
+            return DyNTS_McpClient_Util.parseText(events[events.length - 1]);
+        }
+        return DyNTS_McpClient_Util.parseText(text);
+    }
+    /** A text parsed as JSON when it is JSON, else the text itself (`undefined` stays `undefined`). */
+    static parseText(text) {
+        if (text === undefined) {
+            return undefined;
+        }
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            return text;
+        }
+    }
+    /** The coded error of a tool error payload `{ ok: false, error: { code, message, errorCode } }`. */
+    static toolError(tool, payload) {
+        const failure = payload?.error ?? {};
+        const message = typeof failure.message === 'string' && failure.message ?
+            failure.message : `the tool "${tool}" failed`;
+        return new fsm_dynamo_1.DyFM_Error({
+            status: mcp_error_util_1.DyNTS_McpError_Util.statusOfCode(failure.code),
+            errorCode: failure.errorCode || `${global_settings_const_1.DyNTS_global_settings.systemShortCodeName}|DyNTS-MCC-TOL`,
+            message: message,
+            userMessage: message,
+            additionalContent: { tool: tool, jsonRpcCode: failure.code },
+        });
+    }
+    /** A coded client error. */
+    static error(set) {
+        const error = new fsm_dynamo_1.DyFM_Error({
+            status: set.status,
+            errorCode: `${global_settings_const_1.DyNTS_global_settings.systemShortCodeName}|${set.code}`,
+            message: set.message,
+            userMessage: set.message,
+        });
+        // the network code of an unreachable server, where a CLI looks for it (`DyCLI_Command_Params.exitCodeOf`)
+        if (set.cause) {
+            error.cause = set.cause;
+        }
+        return error;
+    }
+}
+exports.DyNTS_McpClient_Util = DyNTS_McpClient_Util;
+//# sourceMappingURL=mcp-client.util.js.map

package/build/_modules/mcp/_collections/mcp-client.util.js.map

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

package/build/_modules/mcp/_collections/mcp-error.util.d.ts

@@ -30,6 +30,13 @@ export declare class DyNTS_McpError_Util {
      * @param status - the HTTP status of a `DyFM_Error`
      */
     static codeOfStatus(status: number | undefined): DyNTS_McpErrorCode_Type;
+    /**
+     * The HTTP-like status of a JSON-RPC error code — the inverse of `codeOfStatus`, for a CLIENT that turns an MCP error
+     * back into a coded error (HP-DOPL MP-4.5): invalid params → 400 · method not found → 404 · forbidden → 403 ·
+     * conflict → 409 · internal → 500 · any other code → 502 (the server answered with something unknown).
+     * @param code - the JSON-RPC error code
+     */
+    static statusOfCode(code: number | undefined): number;
     /** A generic, caller-safe label of a code. */
     private static labelOf;
     /** Drops the undefined fields, so the serialized data stays compact. */

package/build/_modules/mcp/_collections/mcp-error.util.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mcp-error.util.d.ts","sourceRoot":"","sources":["../../../../src/_modules/mcp/_collections/mcp-error.util.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,uBAAuB,EAAE,MAAM,oCAAoC,CAAC;AAI7E,OAAO,EAAE,sBAAsB,EAAE,MAAM,oDAAoD,CAAC;AAG5F;;;;;;;;;;;;GAYG;AACH,qBAAa,mBAAmB;IAC9B;;;;;OAKG;IACH,MAAM,CAAC,cAAc,CAAC,GAAG,EAAE;QAAE,KAAK,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,YAAY,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE,GAAG,sBAAsB;IAwChH;;;OAGG;IACH,MAAM,CAAC,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,uBAAuB;IAgBxE,8CAA8C;IAC9C,OAAO,CAAC,MAAM,CAAC,OAAO;IAetB,wEAAwE;IACxE,OAAO,CAAC,MAAM,CAAC,gBAAgB;CAShC"}
+{"version":3,"file":"mcp-error.util.d.ts","sourceRoot":"","sources":["../../../../src/_modules/mcp/_collections/mcp-error.util.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,uBAAuB,EAAE,MAAM,oCAAoC,CAAC;AAI7E,OAAO,EAAE,sBAAsB,EAAE,MAAM,oDAAoD,CAAC;AAG5F;;;;;;;;;;;;GAYG;AACH,qBAAa,mBAAmB;IAC9B;;;;;OAKG;IACH,MAAM,CAAC,cAAc,CAAC,GAAG,EAAE;QAAE,KAAK,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,YAAY,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE,GAAG,sBAAsB;IAwChH;;;OAGG;IACH,MAAM,CAAC,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,uBAAuB;IAgBxE;;;;;OAKG;IACH,MAAM,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM;IAiBrD,8CAA8C;IAC9C,OAAO,CAAC,MAAM,CAAC,OAAO;IAetB,wEAAwE;IACxE,OAAO,CAAC,MAAM,CAAC,gBAAgB;CAShC"}