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

package/lib/bin/cli-phase.d.ts

@@ -0,0 +1,28 @@
+import type { Core } from "../core/core.js";
+import type { ServiceCommandInfo } from "../services/servicecommands.js";
+/**
+ * Decide which Core lifecycle phase a CLI command should run at, based on the
+ * phases declared by every service that provides the command.
+ *
+ * Rule:
+ * - All declared phases `"resolved"` → run `Core.resolve()` only (no service.init()).
+ * - All `undefined` or `"initialized"` → run `Core.init()` (full initialization).
+ * - Mixed → throw with an error naming the command and conflicting phases.
+ * - Empty array → `"initialized"` (no providers = safest fallback).
+ *
+ * `undefined` in the input is treated as `"initialized"` (a service declaring no
+ * phase means "no opinion — use the default, full init").
+ * @param phases - per-provider phase declarations collected by `collectServiceCommands`.
+ * @param cmdName - name of the command, included in the mixed-phase error for diagnosability.
+ * @returns the lifecycle phase Core should run at for this command.
+ */
+export declare function selectPhase(phases: Array<"resolved" | "initialized" | undefined>, cmdName?: string): "resolved" | "initialized";
+/**
+ * Boot a Core instance up to the phase required by the given command. Shared
+ * entry point for every cli.ts site that dispatches a `@Command`.
+ * @param core - a freshly-constructed `Core` instance (not yet resolved or initialized).
+ * @param cmdName - name of the command being dispatched.
+ * @param cmdInfo - merged command info from `collectServiceCommands`.
+ */
+export declare function bootCoreForCommand(core: Core, cmdName: string, cmdInfo: ServiceCommandInfo): Promise<void>;
+//# sourceMappingURL=cli-phase.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cli-phase.d.ts","sourceRoot":"","sources":["../../src/bin/cli-phase.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAC;AAEzE;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,WAAW,CACzB,MAAM,EAAE,KAAK,CAAC,UAAU,GAAG,aAAa,GAAG,SAAS,CAAC,EACrD,OAAO,GAAE,MAAoB,GAC5B,UAAU,GAAG,aAAa,CAW5B;AAED;;;;;;GAMG;AACH,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,IAAI,EACV,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,kBAAkB,GAC1B,OAAO,CAAC,IAAI,CAAC,CAOf"}

package/lib/bin/cli-phase.js

@@ -0,0 +1,44 @@
+/**
+ * Decide which Core lifecycle phase a CLI command should run at, based on the
+ * phases declared by every service that provides the command.
+ *
+ * Rule:
+ * - All declared phases `"resolved"` → run `Core.resolve()` only (no service.init()).
+ * - All `undefined` or `"initialized"` → run `Core.init()` (full initialization).
+ * - Mixed → throw with an error naming the command and conflicting phases.
+ * - Empty array → `"initialized"` (no providers = safest fallback).
+ *
+ * `undefined` in the input is treated as `"initialized"` (a service declaring no
+ * phase means "no opinion — use the default, full init").
+ * @param phases - per-provider phase declarations collected by `collectServiceCommands`.
+ * @param cmdName - name of the command, included in the mixed-phase error for diagnosability.
+ * @returns the lifecycle phase Core should run at for this command.
+ */
+export function selectPhase(phases, cmdName = "<unknown>") {
+    if (phases.length === 0)
+        return "initialized";
+    const normalized = phases.map(p => p ?? "initialized");
+    const unique = new Set(normalized);
+    if (unique.size === 1) {
+        return normalized[0];
+    }
+    throw new Error(`Command '${cmdName}' has inconsistent phases across services: ${[...unique].join(", ")}. ` +
+        `All services declaring a command must agree on phase.`);
+}
+/**
+ * Boot a Core instance up to the phase required by the given command. Shared
+ * entry point for every cli.ts site that dispatches a `@Command`.
+ * @param core - a freshly-constructed `Core` instance (not yet resolved or initialized).
+ * @param cmdName - name of the command being dispatched.
+ * @param cmdInfo - merged command info from `collectServiceCommands`.
+ */
+export async function bootCoreForCommand(core, cmdName, cmdInfo) {
+    const phase = selectPhase(cmdInfo.phases, cmdName);
+    if (phase === "resolved") {
+        await core.resolve();
+    }
+    else {
+        await core.init();
+    }
+}
+//# sourceMappingURL=cli-phase.js.map

package/lib/bin/cli-phase.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-phase.js","sourceRoot":"","sources":["../../src/bin/cli-phase.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,WAAW,CACzB,MAAqD,EACrD,OAAO,GAAW,WAAW;IAE7B,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,aAAa,CAAC;IAC9C,MAAM,UAAU,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,aAAa,CAAC,CAAC;IACvD,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,UAAU,CAAC,CAAC;IACnC,IAAI,MAAM,CAAC,IAAI,KAAK,CAAC,EAAE,CAAC;QACtB,OAAO,UAAU,CAAC,CAAC,CAAC,CAAC;IACvB,CAAC;IACD,MAAM,IAAI,KAAK,CACb,YAAY,OAAO,8CAA8C,CAAC,GAAG,MAAM,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI;QACzF,uDAAuD,CAC1D,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,IAAU,EACV,OAAe,EACf,OAA2B;IAE3B,MAAM,KAAK,GAAG,WAAW,CAAC,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnD,IAAI,KAAK,KAAK,UAAU,EAAE,CAAC;QACzB,MAAM,IAAI,CAAC,OAAO,EAAE,CAAC;IACvB,CAAC;SAAM,CAAC;QACN,MAAM,IAAI,CAAC,IAAI,EAAE,CAAC;IACpB,CAAC;AACH,CAAC"}

package/lib/bin/cli.d.ts

@@ -0,0 +1,196 @@
+#!/usr/bin/env node
+import { type Argv } from "yargs";
+import type { JSONSchema7 } from "json-schema";
+import { Application } from "../application/application.js";
+import { type ServiceCommandInfo, type ServiceCommandTarget } from "../services/servicecommands.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: ServiceCommandTarget[]): void;
+/**
+ * Whether a service type is a deployer, from its compiled capabilities
+ *
+ * @param app - the loaded Application
+ * @param type - the service type
+ * @returns true if the type declares the deployer capability
+ */
+export declare function isDeployerType(app: Pick<Application, "getModules">, type: string): boolean;
+/**
+ * Extract the deployment selection from the raw CLI arguments
+ *
+ * `-d <name>` (or `-d<name>`) selects the deployment when it comes before the command name, so a
+ * command keeps its own `-d` alias; `--deployment <name>` (or `--deployment=<name>`) is accepted anywhere.
+ *
+ * @param argv - the raw CLI arguments
+ * @returns the deployment name and the arguments without the deployment option
+ */
+export declare function extractDeploymentArgument(argv: string[]): {
+    deployment?: string;
+    argv: string[];
+};
+/**
+ * Add the units of the selected deployment that run a command as services
+ *
+ * Only the units whose type provides the command are added: the deployers are never
+ * instantiated for the application commands (serve, debug, ...).
+ *
+ * @param app - the loaded Application
+ * @param cmdName - the command name
+ * @param cmdInfo - the command metadata
+ * @returns the names of the units added
+ * @throws CodeError DEPLOYMENT_REQUIRED if only deployers run the command and no unit does
+ */
+export declare function prepareDeploymentUnits(app: Application, cmdName: string, cmdInfo: ServiceCommandInfo): string[];
+/**
+ * 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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"}