@makaio/framework 1.0.0-dev-1779046984397

package/dist/types-Cvrj2ogm.d.mts

@@ -0,0 +1,305 @@
+import { r as LogImportMode, t as LogImporterInfo } from "./index-D1T-PPqF.mjs";
+import * as _$_makaio_bus_core0 from "@makaio/framework/bus";
+import { IMakaioBus } from "@makaio/framework/bus";
+import { LogImportOrchestrator, LogImporter } from "@makaio/framework/adapters";
+import { JsonObject } from "type-fest";
+import { CapabilityService } from "@makaio/framework/services/capability";
+
+//#region packages/services/log-import/src/capability-provider.d.ts
+/**
+ * Minimal registry API required to register providers from capability events.
+ *
+ * `LogImportRegistry` satisfies this interface structurally, enabling the
+ * capability integration module to remain decoupled from the concrete class.
+ */
+interface CapabilityProviderRegistrar {
+  /**
+   * Returns the registration entry for an importer ID, or `undefined`.
+   * @param importerId - Unique importer ID
+   */
+  getImporter(importerId: string): LogImporterRegistration | undefined;
+  /**
+   * Registers a new importer.
+   * @param registration - Importer registration data
+   */
+  register(registration: LogImporterRegistration): Promise<void>;
+  /**
+   * Attaches an orchestrator factory to a registered importer.
+   * @param importerId - Unique importer ID
+   * @param factory - Factory function for mode-specific orchestrators
+   */
+  setOrchestratorFactory(importerId: string, factory: OrchestratorFactory): void;
+  /**
+   * Switches the import mode for a registered importer.
+   * @param importerId - Unique importer ID
+   * @param mode - Target import mode
+   */
+  switchMode(importerId: string, mode: LogImportMode): Promise<void>;
+}
+//#endregion
+//#region packages/services/log-import/src/log-import-registry.d.ts
+/**
+ * Registry for managing log importers and their orchestrator lifecycle.
+ *
+ * Follows the ToolRegistry pattern with key differences:
+ * - Manages orchestrators instead of toolsets
+ * - Lazy orchestrator creation (only when started)
+ * - Auto-detection via detectImporter()
+ * @example
+ * ```typescript
+ * const registry = new LogImportRegistry();
+ * await registry.init();
+ *
+ * // Register an importer
+ * await registry.register({
+ *   id: 'claude-code-1',
+ *   adapterName: 'claude-code-cli',
+ *   displayName: 'Claude Code',
+ *   source: 'adapter',
+ *   importer: myImporter,
+ *   logFilePattern: '**\/session.jsonl',
+ * });
+ *
+ * // Start watching for new sessions
+ * await registry.startImporter('claude-code-1');
+ * ```
+ */
+declare class LogImportRegistry implements CapabilityProviderRegistrar {
+  private readonly bus;
+  private readonly capabilityService?;
+  private readonly registrations;
+  private readonly orchestrators;
+  private readonly cleanupHandlers;
+  private initialized;
+  /**
+   * Creates a new LogImportRegistry instance.
+   * @param options - Optional configuration
+   */
+  constructor(options?: LogImportRegistryOptions);
+  /**
+   * Initializes the registry and registers bus handlers.
+   *
+   * Registers handlers for:
+   * - listImporters: List all registered importers
+   * - scan: Scan log directory for sessions (generic handler)
+   * - uploadFiles: Process uploaded files (generic handler)
+   * - importSession: Lazy-load pick-up for discovered sessions
+   * - capability register: Auto-register adapters that publish log-import capabilities
+   *
+   * Must be called before using the registry.
+   */
+  init(): Promise<void>;
+  /**
+   * Registers a log importer.
+   *
+   * Does not start the orchestrator automatically. Use startImporter() to begin watching.
+   * @param registration - Importer registration data
+   * @throws If an importer with the same ID is already registered
+   */
+  register(registration: LogImporterRegistration): Promise<void>;
+  /**
+   * Unregisters a log importer.
+   *
+   * Stops the orchestrator if running, disposes it, and removes all references.
+   * @param importerId - Unique importer ID
+   * @throws If the importer is not registered
+   */
+  unregister(importerId: string): Promise<void>;
+  /**
+   * Starts the orchestrator for a registered importer.
+   *
+   * Creates the orchestrator if not already created (lazy initialization).
+   * Note: Orchestrator creation requires adapter-specific factory logic,
+   * which is handled externally. This method manages the lifecycle only.
+   * @param importerId - Unique importer ID
+   * @throws If the importer is not registered or orchestrator is not provided
+   */
+  startImporter(importerId: string): Promise<void>;
+  /**
+   * Stops the orchestrator for a registered importer.
+   *
+   * Does nothing if the orchestrator is not running.
+   * @param importerId - Unique importer ID
+   */
+  stopImporter(importerId: string): Promise<void>;
+  /**
+   * Switches the orchestrator mode for a registered importer.
+   *
+   * Stops the current orchestrator (if running), disposes it, creates a new
+   * orchestrator for the requested mode via the registration's factory, and
+   * starts it. When `mode` is `'disabled'`, any running orchestrator is stopped
+   * and cleared without starting a replacement.
+   *
+   * No-op when the importer has no `orchestratorFactory` (no orchestrator
+   * classes were provided at registration time).
+   * @param importerId - Unique importer ID
+   * @param mode - Target import mode
+   * @throws If the importer is not registered
+   */
+  switchMode(importerId: string, mode: LogImportMode): Promise<void>;
+  /**
+   * Convenience method that starts discovery mode for a registered importer.
+   *
+   * Equivalent to calling `switchMode(id, 'discover')`. Provided as a
+   * named shorthand so call sites read as intent rather than mechanism.
+   * @param importerId - Unique importer ID
+   * @returns Promise that resolves when the discovery orchestrator has started
+   * @throws If the importer is not registered
+   */
+  startDiscovery(importerId: string): Promise<void>;
+  /**
+   * Attaches an orchestrator factory to a registered importer.
+   *
+   * Called by the runtime after creating orchestrator class instances so the
+   * registry can reconstruct orchestrators when the mode changes via
+   * {@link switchMode}.
+   * @param importerId - Unique importer ID
+   * @param factory - Factory function that produces orchestrators for a given mode
+   * @throws If the importer is not registered
+   */
+  setOrchestratorFactory(importerId: string, factory: OrchestratorFactory): void;
+  /**
+   * Lists all registered importers with their current status.
+   * @returns Array of importer information
+   */
+  listImporters(): LogImporterInfo[];
+  /**
+   * Gets a registered importer by ID.
+   * @param importerId - Unique importer ID
+   * @returns Importer registration or undefined if not found
+   */
+  getImporter(importerId: string): LogImporterRegistration | undefined;
+  /**
+   * Gets a registered importer by adapter name.
+   * @param adapterName - Adapter name (e.g., 'claude-code-cli', 'codex-app-server')
+   * @returns Importer registration or undefined if not found
+   */
+  getImporterByAdapterName(adapterName: string): LogImporterRegistration | undefined;
+  /**
+   * Auto-detects which importer can handle a log sample.
+   *
+   * Used during log upload to match unknown formats with compatible importers.
+   * @param sample - Sample log content (string or parsed JSON object)
+   * @returns Matching importer registration or undefined if no match
+   */
+  detectImporter(sample: string | JsonObject): LogImporterRegistration | undefined;
+  /**
+   * Registers an orchestrator for a specific importer.
+   *
+   * This is called by adapters/extensions after they create their orchestrator instance.
+   * The registry manages the lifecycle but doesn't create orchestrators itself.
+   * @param importerId - Unique importer ID
+   * @param orchestrator - Orchestrator instance
+   * @throws If the importer is not registered
+   */
+  registerOrchestrator(importerId: string, orchestrator: LogImportOrchestrator): Promise<void>;
+  /**
+   * Cleans up registry resources.
+   *
+   * Stops all running orchestrators and unsubscribes from bus handlers.
+   */
+  destroy(): Promise<void>;
+}
+//#endregion
+//#region packages/services/log-import/src/types.d.ts
+/**
+ * Factory function that creates a {@link LogImportOrchestrator} for a given mode.
+ *
+ * Returns `null` when no orchestrator is available for the requested mode
+ * (e.g., discovery requested but no `LogDiscoveryOrchestratorClass` was
+ * registered for this adapter).
+ * @param mode - Target import mode (never `'disabled'`)
+ * @returns Orchestrator instance or null if the mode requires no orchestrator
+ */
+type OrchestratorFactory = (mode: Exclude<LogImportMode, 'disabled'>) => LogImportOrchestrator | null;
+/**
+ * Public provenance class for a registered log importer.
+ */
+type LogImporterSource = 'adapter' | 'extension';
+/**
+ * Registration entry for a log importer.
+ *
+ * Stores metadata and references needed to manage the importer lifecycle.
+ */
+interface LogImporterRegistration {
+  /**
+   * Unique ID: adapterId for adapters, `package:{name}` for extensions.
+   */
+  id: string;
+  /**
+   * Adapter name used for session lookup and provenance tracking.
+   * @example 'claude-code-cli', 'codex-app-server', 'github-copilot-sdk'
+   */
+  adapterName: string;
+  /**
+   * Human-readable name.
+   * @example 'Claude Code', 'GitHub Copilot SDK'
+   */
+  displayName: string;
+  /**
+   * Source type.
+   */
+  source: LogImporterSource;
+  /**
+   * Importer instance.
+   */
+  importer: LogImporter<unknown, unknown>;
+  /**
+   * Glob pattern for log files.
+   * @example '**\/session.jsonl'
+   */
+  logFilePattern: string;
+  /**
+   * Whether this importer supports manual scan/import operations.
+   * Defaults to true.
+   */
+  supportsManualImport?: boolean;
+  /**
+   * Factory for creating orchestrators for this importer.
+   *
+   * When present, the registry can swap orchestrators on mode change via
+   * {@link LogImportRegistry.switchMode}. Absent when neither
+   * `LogOrchestratorClass` nor `LogDiscoveryOrchestratorClass` was provided.
+   */
+  orchestratorFactory?: OrchestratorFactory;
+}
+/**
+ * Configuration options for LogImportRegistry.
+ */
+interface LogImportRegistryOptions {
+  /**
+   * Message bus instance (defaults to MakaioBus).
+   */
+  bus?: _$_makaio_bus_core0.IMakaioBus;
+  /**
+   * Capability service used to backfill providers registered before init().
+   */
+  capabilityService?: CapabilityService;
+}
+/**
+ * Service instance returned by the log-import composition factory.
+ *
+ * Bundles the {@link LogImportRegistry} and the session-import handler
+ * cleanup so both are torn down together on shutdown.
+ */
+interface LogImportServiceInstance {
+  /** The live log-import registry. */
+  readonly registry: LogImportRegistry;
+  /** Tears down the registry and all session-import handlers. */
+  destroy(): Promise<void>;
+}
+/**
+ * Internal storage for orchestrator instances.
+ */
+interface OrchestratorEntry {
+  /**
+   * Orchestrator instance.
+   */
+  orchestrator: LogImportOrchestrator;
+  /**
+   * Whether orchestrator was started by registry.
+   */
+  isManaged: boolean;
+}
+//#endregion
+export { OrchestratorFactory as a, OrchestratorEntry as i, LogImportServiceInstance as n, LogImportRegistry as o, LogImporterRegistration as r, LogImportRegistryOptions as t };

package/dist/types-DYF5LxZY.d.mts

@@ -0,0 +1,233 @@
+import { z } from "zod";
+import { IMakaioBus } from "@makaio/framework/bus";
+import { CliManifest } from "@makaio/framework/contracts/extension";
+
+//#region packages/kernel/src/cli/types.d.ts
+declare module 'zod' {
+  interface GlobalMeta {
+    /** Short flag alias for CLI options (e.g. `'-p'`, `'-f'`). */
+    short?: string;
+    /** Placeholder shown in help text (e.g. `'<name>'`, `'<path>'`). */
+    placeholder?: string;
+    /** When `true`, treat this field as a positional argument instead of a named option. */
+    positional?: boolean;
+  }
+}
+/**
+ * Injectable output channel for CLI command handlers.
+ *
+ * Handlers write to `ctx.output` instead of `process.stdout`/`process.stderr`
+ * directly. This enables output capture for remote execution via `cli.execute`
+ * and test assertions.
+ */
+interface OutputWriter {
+  /** Write to standard output. */
+  write(text: string): void;
+  /** Write to standard error. */
+  error(text: string): void;
+}
+/**
+ * Execution context provided to CLI command handlers.
+ * @typeParam TArgs - Inferred from the command's Zod schema via `z.infer<T>`.
+ */
+interface CommandContext<TArgs> {
+  /** Parsed and validated command arguments/options. */
+  readonly args: TArgs;
+  /**
+   * Bus client connected to the running Makaio instance.
+   *
+   * `null` when the bus is unavailable and the command opted into offline
+   * execution via {@link CliContribution.beforeRun}. Handlers that declared
+   * themselves runnable without the bus must check for `null` before making
+   * bus calls.
+   */
+  readonly bus: IMakaioBus | null;
+  /** Output channel for writing to stdout/stderr. */
+  readonly output: OutputWriter;
+  /**
+   * Abort signal that is triggered when the process receives SIGINT (Ctrl-C).
+   *
+   * 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.
+   *
+   * Always present — contexts that cannot supply a meaningful signal must use
+   * `AbortSignal.timeout(Infinity)` or a never-aborting controller signal.
+   */
+  readonly signal: AbortSignal;
+  /**
+   * Set the process-style exit code for the current command invocation.
+   *
+   * Local CLI execution forwards this to `process.exitCode`. Remote execution
+   * buffers it into the `cli.execute` RPC response instead of mutating the
+   * server process.
+   * @param exitCode - Command exit code to report.
+   */
+  setExitCode(exitCode: number): void;
+}
+/**
+ * Context provided to {@link CliContribution.beforeRun} for pre-execution
+ * gating decisions.
+ */
+interface BeforeRunContext {
+  /**
+   * Name of the subcommand being invoked (e.g. `'list'`, `'statusline'`).
+   *
+   * 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>;
+  /**
+   * Bus client, or `null` when the server is unreachable.
+   *
+   * Extensions that can operate without the bus inspect this to decide
+   * whether to proceed. Extensions that need a license check can use
+   * the bus (when available) to query license state.
+   */
+  readonly bus: IMakaioBus | null;
+}
+/**
+ * Result of a {@link CliContribution.beforeRun} gate check.
+ *
+ * - `{ proceed: true }` — skip the default bus-required gate and run the
+ *   handler. The handler receives `bus: IMakaioBus | null`.
+ * - `{ proceed: false, message, exitCode? }` — block execution and display
+ *   the message. Defaults to exit code 1.
+ */
+type BeforeRunResult = {
+  readonly proceed: true;
+} | {
+  readonly proceed: false;
+  readonly message: string;
+  readonly exitCode?: number;
+};
+/**
+ * A single CLI subcommand with a Zod schema and strongly-typed handler.
+ *
+ * The schema defines both the data shape (for type inference) and CLI metadata
+ * (descriptions, short flags) via Zod's `.meta()` on each field.
+ * @typeParam T - A `z.ZodObject` whose shape defines the command's options/args.
+ */
+interface CliSubcommandDefinition<T extends z.ZodObject<z.ZodRawShape>> {
+  /** Subcommand name (e.g. `'list'`, `'switch'`). */
+  readonly name: string;
+  /** One-line description shown in help text. */
+  readonly description: string;
+  /** Zod object schema defining the command's options and arguments. */
+  readonly schema: T;
+  /** Handler invoked with the parsed, validated context. */
+  readonly handler: (ctx: CommandContext<z.infer<T>>) => Promise<void>;
+}
+/**
+ * Type-erased subcommand definition for collections.
+ *
+ * When collecting subcommands into arrays or registries, the per-schema generic
+ * is erased. The handler contract is preserved at runtime via the closure
+ * created by {@link defineCliSubcommand}.
+ */
+interface CliSubcommandEntry {
+  /** Subcommand name. */
+  readonly name: string;
+  /** One-line description. */
+  readonly description: string;
+  /** Zod object schema (type-erased for collection storage). */
+  readonly schema: z.ZodObject<z.ZodRawShape>;
+  /** Handler that receives a {@link CommandContext} with the schema's inferred type. */
+  readonly handler: (ctx: CommandContext<unknown>) => Promise<void>;
+}
+/**
+ * Sentinel subcommand name passed to {@link CliContribution.beforeRun} when
+ * the bare interactive invocation (`makaio <name>`) is dispatched.
+ */
+declare const INTERACTIVE_SUBCOMMAND: "__interactive__";
+/**
+ * Convenience {@link BeforeRunResult} for extensions that always proceed.
+ *
+ * Use this as the return value from {@link CliContribution.beforeRun} when
+ * the extension unconditionally opts into bus-optional execution.
+ */
+declare const ALWAYS_PROCEED: BeforeRunResult;
+/**
+ * A plugin's CLI contribution, declared in its `MakaioExtension` manifest.
+ *
+ * Extends {@link CliManifest} (pure-data) with executable code: an optional
+ * interactive TUI handler and typed subcommand definitions. The CLI router
+ * uses {@link CliManifest} for discovery and help generation; this type is
+ * used when the package is loaded and ready to handle commands.
+ *
+ * The CLI router dispatches as follows:
+ * - `makaio account-manager`        → {@link interactive} (if defined)
+ * - `makaio account-manager --help` → auto-generated from subcommands + schema metadata
+ * - `makaio account-manager list`   → matched subcommand handler
+ */
+interface CliContribution extends CliManifest {
+  /**
+   * Interactive TUI launched when the command is invoked without a subcommand.
+   *
+   * When defined, bare `makaio <name>` enters this handler instead of printing
+   * help. Typically renders an Ink TUI that reuses the same bus RPC calls as
+   * the non-interactive subcommands.
+   *
+   * The bus is non-null when no {@link beforeRun} hook is defined (the default
+   * gate ensures a connected bus). When `beforeRun` opts into bus-optional
+   * 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>;
+  /** Typed subcommand definitions with Zod schemas and strongly-typed handlers. */
+  readonly subcommands: ReadonlyArray<CliSubcommandEntry>;
+  /**
+   * Pre-execution gate evaluated before the default bus-required check.
+   *
+   * When provided, this hook **replaces** the default "bus must be connected"
+   * gate. The extension inspects the context (including bus availability) and
+   * decides whether execution should proceed.
+   *
+   * Use cases:
+   * - **Bus-optional commands** — extensions that can operate without the
+   *   server (e.g. `claude-code-statusline`, fire-and-forget hooks).
+   * - **License gates** — paid extensions that need to verify a subscription
+   *   before allowing execution.
+   *
+   * When absent, the CLI framework applies the default behavior: require a
+   * connected bus and fail with a connection error when unavailable.
+   * @param context - Subcommand name, parsed args, and bus availability.
+   * @returns Whether to proceed or block with a message.
+   */
+  readonly beforeRun?: (context: BeforeRunContext) => BeforeRunResult | Promise<BeforeRunResult>;
+}
+/**
+ * Assert that the bus is available and narrow the type to non-null.
+ *
+ * Handlers that require the bus (i.e. extensions without a `beforeRun` hook
+ * that permits offline execution) call this at the top of their handler to
+ * get a typed non-null bus reference. Throws if the bus is unexpectedly null
+ * — which should not happen when the default bus-required gate is active.
+ *
+ * Works with both subcommand {@link CommandContext} and interactive handler
+ * contexts — any object with a `bus` property satisfies the signature.
+ * @param ctx - Context containing a potentially null bus reference.
+ * @returns The non-null bus instance.
+ */
+declare function requireBus(ctx: {
+  readonly bus: IMakaioBus | null;
+}): IMakaioBus;
+/**
+ * Define a CLI subcommand with full type inference from schema to handler.
+ *
+ * This is an identity function whose only purpose is to create a scope where
+ * TypeScript infers `T` from `schema` and flows it into `handler`. No runtime
+ * cost. Same pattern as Vite's `defineConfig()` or Vue's `defineComponent()`.
+ * @param name - Subcommand name.
+ * @param description - One-line description for help text.
+ * @param schema - Zod object schema defining options/arguments.
+ * @param handler - Async handler receiving the typed {@link CommandContext}.
+ * @returns A {@link CliSubcommandEntry} suitable for inclusion in a {@link CliContribution}.
+ */
+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 };