@webda/core 4.0.0-beta.2 → 4.0.0-beta.3

package/lib/bin/cli.d.ts

@@ -0,0 +1,161 @@
+#!/usr/bin/env node
+import { type Argv } from "yargs";
+import type { JSONSchema7 } from "json-schema";
+import { Application } from "../application/application.js";
+import { type ConsoleLogStream } from "@webda/workout";
+/**
+ * Operation entry from operations.json
+ */
+export interface OperationEntry {
+    id: string;
+    input: string;
+    output: string;
+}
+/**
+ * Format of the .webda/operations.json file
+ */
+export interface OperationsFile {
+    operations: Record<string, OperationEntry>;
+    schemas: Record<string, JSONSchema7>;
+}
+/**
+ * Parsed operation call ready for execution
+ */
+export interface OperationCall {
+    /** Operation ID (e.g., "Task.Create") */
+    id: string;
+    /** Parsed parameters (e.g., { uuid: "abc123" }) */
+    parameters: Record<string, any>;
+    /** Parsed input body */
+    input?: any;
+}
+export type OperationHandler = (call: OperationCall) => Promise<void>;
+/**
+ * Load .webda/operations.json from an application directory
+ * @param appPath - the application path
+ * @returns the result
+ */
+export declare function loadOperations(appPath?: string): OperationsFile;
+/**
+ * Build a yargs CLI from an operations.json file
+ *
+ * Groups operations by their prefix (e.g., "Task") and creates nested
+ * subcommands for each action (e.g., "create", "get", "delete").
+ *
+ * Usage examples (given Task CRUD operations):
+ *   webda task create --json '{"title":"My Task"}'
+ *   webda task get <uuid>
+ *   webda task delete <uuid>
+ *   webda tasks query --query "status = 'active'"
+ *
+ * @param ops Loaded operations file
+ * @param handler Called when an operation command is invoked
+ * @param argv Command-line arguments (defaults to process.argv.slice(2))
+ * @returns the result
+ */
+export declare function buildCli(ops: OperationsFile, handler: OperationHandler, argv?: string[]): Argv;
+/**
+ * Add service commands (from `@Command` decorators) to a yargs CLI instance.
+ *
+ * Reads commands from `webda.module.json` via the Application and registers
+ * them as yargs commands. Subcommands (space-separated names like `"aws s3"`)
+ * are nested as yargs subcommand groups.
+ *
+ * A global `--service` option is added to filter which services handle a command
+ * when multiple services declare the same command name.
+ *
+ * @param cli - The yargs CLI instance to add commands to
+ * @param serviceCommands - Command map from {@link collectServiceCommands}
+ * @param handler - Called when a service command is invoked, receives command name and parsed args
+ *
+ * @example
+ * ```typescript
+ * import { collectServiceCommands, addServiceCommandsToCli } from "@webda/core";
+ *
+ * const cmds = collectServiceCommands(app);
+ * const cli = yargs().scriptName("webda");
+ * addServiceCommandsToCli(cli, cmds, async (cmdName, args) => {
+ *   await executeServiceCommand(cmdName, cmds[cmdName], args, core.getServices(), args.service?.split(","));
+ * });
+ * ```
+ * @returns the result
+ */
+export declare function addServiceCommandsToCli(cli: Argv, serviceCommands: {
+    [name: string]: import("../services/servicecommands.js").ServiceCommandInfo;
+}, handler: (cmdName: string, args: Record<string, any>) => Promise<void>): Argv;
+/**
+ * Resolve where log lines go, from the raw CLI arguments
+ *
+ * `--log-stream=auto` (the default) sends logs to stderr when stdout is not a
+ * TTY, so a piped command result stays clean; `stdout` or `stderr` force it.
+ * Read from raw argv because the logger is created before yargs parses.
+ * @param argv - the raw CLI arguments
+ * @param stdoutIsTTY - whether stdout is a terminal
+ * @returns the stream for log lines
+ */
+export declare function resolveLogStream(argv: string[], stdoutIsTTY: boolean): ConsoleLogStream;
+/**
+ * Whether to route `console.*` calls to the logger, from the raw CLI arguments
+ * @param argv - the raw CLI arguments
+ * @returns false when `--no-console-patch` is given
+ */
+export declare function shouldPatchConsole(argv: string[]): boolean;
+/**
+ * Ensure services that declare a command exist in the app configuration.
+ * If a service type is not already configured, it is injected with a generated name.
+ *
+ * @param app - The loaded Application
+ * @param services - Service targets from the command metadata
+ */
+export declare function ensureCommandServices(app: Application, services: import("../services/servicecommands.js").ServiceCommandTarget[]): void;
+/**
+ * Resolve required capabilities for a command, auto-injecting default providers
+ * into the app config if not already configured.
+ *
+ * @param app - The loaded Application
+ * @param requires - Capability names required by the command
+ */
+export declare function resolveCapabilities(app: Application, requires: string[]): void;
+/**
+ * Shutdown sequence of a CLI command: stop Core once, then exit
+ *
+ * The command finishing and a signal can both trigger it: only the first call counts.
+ *
+ * @param core - the Core to stop
+ * @param core.stop - stop every service
+ * @param exit - process exit, replaceable for tests
+ * @returns `shutdown(code)` to stop then exit with the code, and `interrupt()` for SIGINT/SIGTERM
+ */
+export declare function createCommandShutdown(core: {
+    stop(): Promise<void>;
+}, exit?: (code: number) => void): {
+    shutdown: (code: number) => Promise<void>;
+    interrupt: () => Promise<void>;
+};
+/**
+ * Run `interrupt` once on SIGINT or SIGTERM (Kubernetes stops pods with SIGTERM)
+ *
+ * Later signals are ignored while shutting down: on a terminal, Ctrl+C reaches both
+ * the launcher (which forwards it) and the CLI.
+ *
+ * @param interrupt - the interruption handler
+ */
+export declare function onInterrupt(interrupt: () => Promise<void>): void;
+/**
+ * Run a service command until it settles, then shut down with its exit code
+ *
+ * A command that throws exits with code 1.
+ *
+ * @param cmdName - the command name, for logs
+ * @param execute - run the command and resolve with its exit code
+ * @param shutdown - stop Core then exit with the code
+ */
+export declare function settleServiceCommand(cmdName: string, execute: () => Promise<number>, shutdown: (code: number) => Promise<void>): Promise<void>;
+/**
+ * Log the outcome of a service command started without waiting for it (watch mode)
+ *
+ * @param cmdName - the command name, for logs
+ * @param execution - the running command, resolving with its exit code
+ */
+export declare function reportServiceCommand(cmdName: string, execution: Promise<number>): void;
+//# sourceMappingURL=cli.d.ts.map

package/lib/bin/cli.d.ts.map

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