@makaio/framework 1.0.0-dev-1779051654000 → 1.0.0-dev-1781023871421

package/dist/{types-DYF5LxZY.d.mts → types-MfJZ67e9.d.mts}

@@ -45,11 +45,13 @@ interface CommandContext<TArgs> {
   /** Output channel for writing to stdout/stderr. */
   readonly output: OutputWriter;
   /**
-   * Abort signal that is triggered when the process receives SIGINT (Ctrl-C).
+   * Abort signal that is triggered when local CLI execution receives SIGINT,
+   * SIGTERM, or SIGHUP.
    *
-   * Long-running commands (e.g. `watch`) should honour this signal to perform
-   * clean teardown instead of relying on process termination. Short-lived
-   * commands may ignore it.
+   * Commands must honour this signal before starting new work and during
+   * long-running operations. The local CLI translates process signals into this
+   * signal so command-owned `finally` blocks can dispose embedded runtimes
+   * before the process exits with the conventional signal exit code.
    *
    * Always present — contexts that cannot supply a meaningful signal must use
    * `AbortSignal.timeout(Infinity)` or a never-aborting controller signal.
@@ -149,6 +151,64 @@ declare const INTERACTIVE_SUBCOMMAND: "__interactive__";
  * the extension unconditionally opts into bus-optional execution.
  */
 declare const ALWAYS_PROCEED: BeforeRunResult;
+/**
+ * Execution context provided to bare interactive CLI handlers.
+ */
+interface InteractiveCommandContext {
+  /**
+   * Bus client connected to the running Makaio instance.
+   *
+   * `null` when the bus is unavailable and the contribution's `beforeRun`
+   * hook opted into bus-optional execution.
+   */
+  readonly bus: IMakaioBus | null;
+  /**
+   * Abort signal triggered when local CLI execution receives SIGINT, SIGTERM,
+   * or SIGHUP.
+   *
+   * Interactive handlers must observe this signal and tear down any TUI
+   * renderer they own, because local CLI signal handling defers immediate
+   * process termination until command-owned cleanup has run.
+   */
+  readonly signal: AbortSignal;
+}
+/**
+ * Context passed to {@link CliContribution.provideBus} so the extension can
+ * inspect the incoming invocation before deciding whether to bootstrap a bus.
+ */
+interface ProvideBusContext {
+  /**
+   * Name of the subcommand being invoked (e.g. `'run'`, `'start'`).
+   *
+   * Set to {@link INTERACTIVE_SUBCOMMAND} (`'__interactive__'`) when the bare
+   * interactive invocation is dispatched.
+   */
+  readonly subcommandName: string;
+  /** Parsed and validated arguments for the subcommand. */
+  readonly args: Record<string, unknown>;
+  /** Absolute path of the working directory from which the CLI was invoked. */
+  readonly cwd: string;
+}
+/**
+ * Handle returned by {@link CliContribution.provideBus} when the extension
+ * successfully bootstraps an embedded bus.
+ *
+ * The CLI router holds this handle for the duration of the command invocation
+ * and calls `dispose` during teardown to shut down the embedded bus cleanly.
+ */
+interface EmbeddedBusHandle {
+  /** The live bus instance to inject into command handlers. */
+  readonly bus: IMakaioBus;
+  /**
+   * Shut down the embedded bus and release all associated resources.
+   *
+   * Called by the CLI router after the command handler completes (or errors).
+   * Implementations must be idempotent — calling `dispose` more than once must
+   * not throw.
+   * @returns A promise that resolves when teardown is complete.
+   */
+  dispose(): Promise<void>;
+}
 /**
  * A plugin's CLI contribution, declared in its `MakaioExtension` manifest.
  *
@@ -161,6 +221,14 @@ declare const ALWAYS_PROCEED: BeforeRunResult;
  * - `makaio account-manager`        → {@link interactive} (if defined)
  * - `makaio account-manager --help` → auto-generated from subcommands + schema metadata
  * - `makaio account-manager list`   → matched subcommand handler
+ *
+ * Bus resolution order (first match wins):
+ * 1. External daemon connection — if the server is reachable, its bus is used.
+ * 2. {@link provideBus} — extension embeds its own bus (standalone mode).
+ * 3. `null` bus — passed to handlers only when {@link beforeRun} opts in.
+ *
+ * {@link beforeRun} is evaluated **after** bus resolution completes so that its
+ * context always reflects the final resolved bus state.
  */
 interface CliContribution extends CliManifest {
   /**
@@ -175,13 +243,12 @@ interface CliContribution extends CliManifest {
    * execution, `bus` may be `null` — use {@link requireBus} at the top of the
    * handler if the TUI needs bus RPC calls.
    */
-  readonly interactive?: (ctx: {
-    bus: IMakaioBus | null;
-  }) => Promise<void>;
+  readonly interactive?: (ctx: InteractiveCommandContext) => Promise<void>;
   /** Typed subcommand definitions with Zod schemas and strongly-typed handlers. */
   readonly subcommands: ReadonlyArray<CliSubcommandEntry>;
   /**
-   * Pre-execution gate evaluated before the default bus-required check.
+   * Pre-execution gate evaluated **after** bus resolution (including any
+   * embedded bus from {@link provideBus}) completes.
    *
    * When provided, this hook **replaces** the default "bus must be connected"
    * gate. The extension inspects the context (including bus availability) and
@@ -199,6 +266,21 @@ interface CliContribution extends CliManifest {
    * @returns Whether to proceed or block with a message.
    */
   readonly beforeRun?: (context: BeforeRunContext) => BeforeRunResult | Promise<BeforeRunResult>;
+  /**
+   * Bootstrap an embedded bus for standalone or in-process execution.
+   *
+   * When defined and {@link CliManifest.canProvideBus} is `true` in the
+   * manifest, the CLI router calls this hook **only when no external daemon
+   * connection was established**. If it returns a non-null handle the embedded
+   * bus is used for the lifetime of the command; the router calls
+   * {@link EmbeddedBusHandle.dispose} after the handler completes.
+   *
+   * Returning `null` signals that this invocation should not use an embedded
+   * bus and the handler receives `bus: null`.
+   * @param context - Subcommand name, parsed args, and working directory.
+   * @returns A live bus handle, or `null` to fall through to normal connection.
+   */
+  readonly provideBus?: (context: ProvideBusContext) => Promise<EmbeddedBusHandle | null>;
 }
 /**
  * Assert that the bus is available and narrow the type to non-null.
@@ -230,4 +312,4 @@ declare function requireBus(ctx: {
  */
 declare function defineCliSubcommand<T extends z.ZodObject<z.ZodRawShape>>(name: string, description: string, schema: T, handler: (ctx: CommandContext<z.infer<T>>) => Promise<void>): CliSubcommandEntry;
 //#endregion
-export { CliSubcommandDefinition as a, INTERACTIVE_SUBCOMMAND as c, requireBus as d, CliContribution as i, OutputWriter as l, BeforeRunContext as n, CliSubcommandEntry as o, BeforeRunResult as r, CommandContext as s, ALWAYS_PROCEED as t, defineCliSubcommand as u };
+export { CliSubcommandDefinition as a, EmbeddedBusHandle as c, ProvideBusContext as d, defineCliSubcommand as f, CliContribution as i, INTERACTIVE_SUBCOMMAND as l, BeforeRunContext as n, CliSubcommandEntry as o, requireBus as p, BeforeRunResult as r, CommandContext as s, ALWAYS_PROCEED as t, OutputWriter as u };

package/dist/{types-6WxLfoM3.d.mts → types-dyP-bXXE.d.mts}

@@ -1,6 +1,6 @@
 import { LibSQLDatabase } from "drizzle-orm/libsql";
 
-//#region packages/storage/drizzle/src/types.d.ts
+//#region storage/drizzle/src/types.d.ts
 /**
  * Canonical database type alias for all Makaio storage consumers.
  *