@cleocode/cleo 2026.4.57 → 2026.4.59

package/dist/dispatch/adapters/cli.js

@@ -0,0 +1,331 @@
+/**
+ * CLI Adapter for the CQRS Dispatch Layer.
+ *
+ * Provides dispatchFromCli() — the single entry point for all CLI commands
+ * that route through the dispatch pipeline. Also exports getCliDispatcher()
+ * for commands needing custom output handling.
+ *
+ * @epic T4820
+ * @task T4818
+ */
+import { randomUUID } from 'node:crypto';
+import { existsSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { catalog, registerSkillLibraryFromPath } from '@cleocode/caamp';
+import { autoRecordDispatchTokenUsage, getProjectRoot, hooks } from '@cleocode/core/internal';
+import { cliError, cliOutput } from '../../cli/renderers/index.js';
+import { Dispatcher } from '../dispatcher.js';
+import { createDomainHandlers } from '../domains/index.js';
+import { createAudit } from '../middleware/audit.js';
+import { createFieldFilter } from '../middleware/field-filter.js';
+import { createSanitizer } from '../middleware/sanitizer.js';
+import { createSessionResolver } from '../middleware/session-resolver.js';
+import { createTelemetry } from '../middleware/telemetry.js';
+// Reverse mapping from string error codes to numeric exit codes.
+// Used when dispatch handlers return string error codes without exitCode.
+const ERROR_CODE_TO_EXIT = {
+    E_NOT_FOUND: 4,
+    E_INVALID_INPUT: 2,
+    E_FILE_ERROR: 3,
+    E_DEPENDENCY: 5,
+    E_VALIDATION: 6,
+    E_RETRYABLE: 7,
+    E_CONFIG_ERROR: 8,
+    E_PARENT_NOT_FOUND: 10,
+    E_DEPTH_EXCEEDED: 11,
+    E_SIBLING_LIMIT: 12,
+    E_CIRCULAR_DEP: 14,
+    E_INVALID_PARENT_TYPE: 13,
+    E_ORPHAN_DETECTED: 15,
+    E_HAS_CHILDREN: 16,
+    E_TASK_COMPLETED: 17, // ExitCode.TASK_COMPLETED — canonical value from @cleocode/contracts
+    E_HAS_DEPENDENTS: 19,
+    E_CHECKSUM_MISMATCH: 20,
+    E_SESSION_EXISTS: 30,
+    E_SESSION_NOT_FOUND: 31,
+    E_SCOPE_CONFLICT: 32,
+    E_ACTIVE_TASK_REQUIRED: 38,
+    E_INVALID_OPERATION: 2,
+    E_MISSING_PARAMS: 2,
+    E_NO_HANDLER: 1,
+    E_INTERNAL: 1,
+};
+// ---------------------------------------------------------------------------
+// CAAMP skill library auto-registration
+// ---------------------------------------------------------------------------
+/**
+ * Best-effort registration of the CAAMP skill library.
+ *
+ * Resolves the `@cleocode/skills` package via Node module resolution,
+ * falling back to workspace monorepo path. Non-fatal: if the library
+ * cannot be found, catalog-dependent operations (skills validate/dispatch/deps)
+ * will return a helpful error instead of crashing.
+ */
+function ensureCaampLibrary() {
+    // Already registered (e.g. via `cleo init` or env var) — nothing to do
+    if (catalog.isCatalogAvailable())
+        return;
+    try {
+        // Strategy 1: resolve @cleocode/skills via Node module resolution
+        let skillsRoot = null;
+        try {
+            const req = createRequire(import.meta.url);
+            const skillsPkgJson = req.resolve('@cleocode/skills/package.json');
+            const candidate = dirname(skillsPkgJson);
+            if (existsSync(join(candidate, 'skills.json'))) {
+                skillsRoot = candidate;
+            }
+        }
+        catch {
+            // Not resolvable — try fallback
+        }
+        // Strategy 2: workspace monorepo path (packages/skills/)
+        if (!skillsRoot) {
+            const thisFile = fileURLToPath(import.meta.url);
+            const packageRoot = join(dirname(thisFile), '..', '..', '..', '..', '..');
+            const candidate = join(packageRoot, 'packages', 'skills');
+            if (existsSync(join(candidate, 'skills.json'))) {
+                skillsRoot = candidate;
+            }
+        }
+        if (skillsRoot) {
+            registerSkillLibraryFromPath(skillsRoot);
+        }
+    }
+    catch {
+        // Non-fatal — catalog operations will degrade gracefully
+    }
+}
+// ---------------------------------------------------------------------------
+// Lazy singleton dispatcher
+// ---------------------------------------------------------------------------
+let _dispatcher = null;
+/**
+ * Get or create the singleton CLI dispatcher.
+ *
+ * Creates a Dispatcher with all 9 domain handlers and sanitizer middleware.
+ * No rate limiter — CLI is a single-user tool.
+ */
+export function getCliDispatcher() {
+    if (!_dispatcher) {
+        _dispatcher = createCliDispatcher();
+    }
+    return _dispatcher;
+}
+/**
+ * Best-effort lookup of the active session ID from SQLite.
+ * Used by session-resolver middleware for CLI commands.
+ * Returns null on any failure (many CLI commands don't need a session).
+ *
+ * @epic T4959
+ */
+async function lookupCliSession() {
+    try {
+        const { getActiveSession } = await import('@cleocode/core/internal');
+        const session = await getActiveSession();
+        return session?.id ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Factory: creates a Dispatcher with all domain handlers + session-resolver,
+ * sanitizer, field-filter, and audit middleware.
+ *
+ * @epic T4959 — added session-resolver + audit to CLI pipeline
+ */
+export function createCliDispatcher() {
+    // Ensure the CAAMP skill catalog is available for tools domain operations
+    ensureCaampLibrary();
+    const handlers = createDomainHandlers();
+    return new Dispatcher({
+        handlers,
+        middlewares: [
+            createSessionResolver(lookupCliSession), // T4959: session identity first
+            createSanitizer(() => getProjectRoot()),
+            createFieldFilter(),
+            createAudit(), // T4959: CLI now gets audit trail
+            createTelemetry(), // T624: opt-in self-improvement telemetry
+        ],
+    });
+}
+/**
+ * Reset the singleton dispatcher (for testing).
+ */
+export function resetCliDispatcher() {
+    _dispatcher = null;
+}
+// ---------------------------------------------------------------------------
+// Main adapter function
+// ---------------------------------------------------------------------------
+/**
+ * Build a DispatchRequest, dispatch it, and handle output/errors.
+ *
+ * This is the primary entry point for migrated CLI commands:
+ *   await dispatchFromCli('query', 'tasks', 'show', { taskId }, { command: 'show' });
+ *
+ * Automatically honors global --field/--fields/--mvi flags from the FieldContext:
+ * - --field <name>   → plain-text extraction, no JSON envelope
+ * - --fields <list>  → field-filter middleware filters the JSON response
+ * - --mvi <level>    → envelope verbosity passed to field-filter middleware
+ *
+ * On success: calls cliOutput(response.data, outputOpts)
+ * On error: calls cliError(message, exitCode) + process.exit(exitCode)
+ *
+ * @epic T4953
+ * @task T4955
+ */
+export async function dispatchFromCli(gateway, domain, operation, params, outputOpts) {
+    const dispatcher = getCliDispatcher();
+    const projectRoot = getProjectRoot();
+    const dispatchStart = Date.now();
+    // Dispatch PromptSubmit hook (best-effort, fire-and-forget)
+    hooks
+        .dispatch('PromptSubmit', projectRoot, {
+        timestamp: new Date().toISOString(),
+        gateway,
+        domain,
+        operation,
+        source: 'cli',
+    })
+        .catch(() => {
+        /* hook errors are non-fatal */
+    });
+    const response = await dispatcher.dispatch({
+        gateway,
+        domain,
+        operation,
+        params,
+        source: 'cli',
+        requestId: randomUUID(),
+    });
+    // Dispatch ResponseComplete hook (best-effort, fire-and-forget)
+    hooks
+        .dispatch('ResponseComplete', projectRoot, {
+        timestamp: new Date().toISOString(),
+        gateway,
+        domain,
+        operation,
+        success: response.success,
+        durationMs: Date.now() - dispatchStart,
+        errorCode: response.error?.code,
+    })
+        .catch(() => {
+        /* hook errors are non-fatal */
+    });
+    if (response.success) {
+        await autoRecordDispatchTokenUsage({
+            requestPayload: params,
+            responsePayload: { data: response.data, page: response.page },
+            transport: 'cli',
+            gateway,
+            domain,
+            operation,
+            sessionId: response.meta.sessionId,
+            requestId: response.meta.requestId,
+            cwd: getProjectRoot(),
+        });
+        const opts = {
+            command: outputOpts?.command ?? operation,
+            operation: outputOpts?.operation ?? `${domain}.${operation}`,
+            ...outputOpts,
+        };
+        if (opts.page === undefined && response.page !== undefined) {
+            opts.page = response.page;
+        }
+        cliOutput(response.data, opts);
+    }
+    else {
+        // Derive exit code from the string error code when exitCode is not set
+        const errorCode = response.error?.code ?? 'E_GENERAL';
+        const exitCode = response.error?.exitCode ?? ERROR_CODE_TO_EXIT[errorCode] ?? 1;
+        cliError(response.error?.message ?? 'Unknown error', exitCode, {
+            name: errorCode,
+            details: response.error?.details,
+            fix: response.error?.fix,
+            alternatives: response.error?.alternatives,
+        }, {
+            operation: `${domain}.${operation}`,
+            requestId: response.meta.requestId,
+            duration_ms: response.meta.duration_ms,
+            timestamp: response.meta.timestamp,
+            ...(response.meta.sessionId ? { sessionId: response.meta.sessionId } : {}),
+        });
+        process.exit(exitCode);
+    }
+}
+/**
+ * Handle an error response from dispatchRaw().
+ *
+ * Calls cliError() and process.exit() when the response indicates failure.
+ * No-op when response.success is true.
+ */
+export function handleRawError(response, _opts) {
+    if (response.success)
+        return;
+    const errorCode = response.error?.code ?? 'E_GENERAL';
+    const exitCode = response.error?.exitCode ?? ERROR_CODE_TO_EXIT[errorCode] ?? 1;
+    cliError(response.error?.message ?? 'Unknown error', exitCode, {
+        name: errorCode,
+        details: response.error?.details,
+        fix: response.error?.fix,
+        alternatives: response.error?.alternatives,
+    }, {
+        operation: _opts.operation,
+        requestId: response.meta.requestId,
+        duration_ms: response.meta.duration_ms,
+        timestamp: response.meta.timestamp,
+        ...(response.meta.sessionId ? { sessionId: response.meta.sessionId } : {}),
+    });
+    process.exit(exitCode);
+}
+/**
+ * Dispatch and return the raw response without handling output.
+ *
+ * For commands that need custom output logic (pagination, conditional
+ * messages, etc.), call this instead of dispatchFromCli().
+ */
+export async function dispatchRaw(gateway, domain, operation, params) {
+    const dispatcher = getCliDispatcher();
+    const projectRoot = getProjectRoot();
+    const dispatchStart = Date.now();
+    // Dispatch PromptSubmit hook (best-effort, fire-and-forget)
+    hooks
+        .dispatch('PromptSubmit', projectRoot, {
+        timestamp: new Date().toISOString(),
+        gateway,
+        domain,
+        operation,
+        source: 'cli',
+    })
+        .catch(() => {
+        /* hook errors are non-fatal */
+    });
+    const response = await dispatcher.dispatch({
+        gateway,
+        domain,
+        operation,
+        params,
+        source: 'cli',
+        requestId: randomUUID(),
+    });
+    // Dispatch ResponseComplete hook (best-effort, fire-and-forget)
+    hooks
+        .dispatch('ResponseComplete', projectRoot, {
+        timestamp: new Date().toISOString(),
+        gateway,
+        domain,
+        operation,
+        success: response.success,
+        durationMs: Date.now() - dispatchStart,
+        errorCode: response.error?.code,
+    })
+        .catch(() => {
+        /* hook errors are non-fatal */
+    });
+    return response;
+}
+//# sourceMappingURL=cli.js.map

package/dist/dispatch/adapters/cli.js.map

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

package/dist/dispatch/context/session-context.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Process-scoped session context for the CLEO dispatch layer.
+ *
+ * Each Claude Code conversation spawns its own process, so 5 concurrent
+ * agents = 5 isolated SessionContext instances with zero shared state.
+ * This replaces the fragile process.env.CLEO_SESSION_ID mechanism.
+ *
+ * @epic T4959
+ */
+/**
+ * Immutable snapshot of the bound session context.
+ */
+export interface SessionContext {
+    /** Active session ID. */
+    sessionId: string;
+    /** Session scope. */
+    scope: {
+        type: string;
+        epicId?: string;
+    };
+    /** Whether full audit logging is enabled for behavioral grading. */
+    gradeMode: boolean;
+    /** PID of the process that bound this context. */
+    agentPid: number;
+    /** ISO timestamp when this context was bound. */
+    boundAt: string;
+}
+/**
+ * Bind a session to the current process.
+ * Called by session.start mutation handler after successful session creation.
+ *
+ * @throws if a session is already bound (call unbindSession first).
+ */
+export declare function bindSession(ctx: Omit<SessionContext, 'agentPid' | 'boundAt'>): SessionContext;
+/**
+ * Get the currently bound session context, or null if none is bound.
+ */
+export declare function getBoundSession(): SessionContext | null;
+/**
+ * Check whether a session is currently bound.
+ */
+export declare function hasSession(): boolean;
+/**
+ * Unbind the current session context.
+ * Called by session.end mutation handler.
+ *
+ * @returns The unbound context, or null if nothing was bound.
+ */
+export declare function unbindSession(): SessionContext | null;
+/**
+ * Reset the session context (for testing only).
+ */
+export declare function resetSessionContext(): void;
+//# sourceMappingURL=session-context.d.ts.map

package/dist/dispatch/context/session-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-context.d.ts","sourceRoot":"","sources":["../../../src/dispatch/context/session-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,yBAAyB;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,qBAAqB;IACrB,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACzC,oEAAoE;IACpE,SAAS,EAAE,OAAO,CAAC;IACnB,kDAAkD;IAClD,QAAQ,EAAE,MAAM,CAAC;IACjB,iDAAiD;IACjD,OAAO,EAAE,MAAM,CAAC;CACjB;AAQD;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,IAAI,CAAC,cAAc,EAAE,UAAU,GAAG,SAAS,CAAC,GAAG,cAAc,CAa7F;AAED;;GAEG;AACH,wBAAgB,eAAe,IAAI,cAAc,GAAG,IAAI,CAEvD;AAED;;GAEG;AACH,wBAAgB,UAAU,IAAI,OAAO,CAEpC;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,IAAI,cAAc,GAAG,IAAI,CAIrD;AAED;;GAEG;AACH,wBAAgB,mBAAmB,IAAI,IAAI,CAE1C"}

package/dist/dispatch/context/session-context.js

@@ -0,0 +1,61 @@
+/**
+ * Process-scoped session context for the CLEO dispatch layer.
+ *
+ * Each Claude Code conversation spawns its own process, so 5 concurrent
+ * agents = 5 isolated SessionContext instances with zero shared state.
+ * This replaces the fragile process.env.CLEO_SESSION_ID mechanism.
+ *
+ * @epic T4959
+ */
+// ---------------------------------------------------------------------------
+// Module-level singleton
+// ---------------------------------------------------------------------------
+let _context = null;
+/**
+ * Bind a session to the current process.
+ * Called by session.start mutation handler after successful session creation.
+ *
+ * @throws if a session is already bound (call unbindSession first).
+ */
+export function bindSession(ctx) {
+    if (_context) {
+        throw new Error(`Session already bound: ${_context.sessionId}. ` +
+            `Call unbindSession() before binding a new session.`);
+    }
+    _context = {
+        ...ctx,
+        agentPid: process.pid,
+        boundAt: new Date().toISOString(),
+    };
+    return _context;
+}
+/**
+ * Get the currently bound session context, or null if none is bound.
+ */
+export function getBoundSession() {
+    return _context;
+}
+/**
+ * Check whether a session is currently bound.
+ */
+export function hasSession() {
+    return _context !== null;
+}
+/**
+ * Unbind the current session context.
+ * Called by session.end mutation handler.
+ *
+ * @returns The unbound context, or null if nothing was bound.
+ */
+export function unbindSession() {
+    const prev = _context;
+    _context = null;
+    return prev;
+}
+/**
+ * Reset the session context (for testing only).
+ */
+export function resetSessionContext() {
+    _context = null;
+}
+//# sourceMappingURL=session-context.js.map

package/dist/dispatch/context/session-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-context.js","sourceRoot":"","sources":["../../../src/dispatch/context/session-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAkBH,8EAA8E;AAC9E,yBAAyB;AACzB,8EAA8E;AAE9E,IAAI,QAAQ,GAA0B,IAAI,CAAC;AAE3C;;;;;GAKG;AACH,MAAM,UAAU,WAAW,CAAC,GAAiD;IAC3E,IAAI,QAAQ,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CACb,0BAA0B,QAAQ,CAAC,SAAS,IAAI;YAC9C,oDAAoD,CACvD,CAAC;IACJ,CAAC;IACD,QAAQ,GAAG;QACT,GAAG,GAAG;QACN,QAAQ,EAAE,OAAO,CAAC,GAAG;QACrB,OAAO,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;KAClC,CAAC;IACF,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,eAAe;IAC7B,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,UAAU;IACxB,OAAO,QAAQ,KAAK,IAAI,CAAC;AAC3B,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,aAAa;IAC3B,MAAM,IAAI,GAAG,QAAQ,CAAC;IACtB,QAAQ,GAAG,IAAI,CAAC;IAChB,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,mBAAmB;IACjC,QAAQ,GAAG,IAAI,CAAC;AAClB,CAAC"}

package/dist/dispatch/dispatcher.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Central Dispatcher -- Routes requests through middleware to domain handlers.
+ *
+ * The dispatcher is the single entry point for the CLI adapter.
+ * It resolves operations, validates parameters, runs the middleware pipeline,
+ * and delegates to the appropriate domain handler.
+ *
+ * Flow: DispatchRequest → resolve → param validation → middleware → handler
+ *
+ * @epic T4820
+ */
+import type { DispatchRequest, DispatchResponse, DomainHandler, Middleware } from './types.js';
+export interface DispatcherConfig {
+    handlers: Map<string, DomainHandler>;
+    middlewares?: Middleware[];
+}
+export declare class Dispatcher {
+    private handlers;
+    private pipeline;
+    constructor(config: DispatcherConfig);
+    dispatch(request: DispatchRequest): Promise<DispatchResponse>;
+}
+//# sourceMappingURL=dispatcher.d.ts.map

package/dist/dispatch/dispatcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dispatcher.d.ts","sourceRoot":"","sources":["../../src/dispatch/dispatcher.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAKH,OAAO,KAAK,EAAE,eAAe,EAAE,gBAAgB,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE/F,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;IACrC,WAAW,CAAC,EAAE,UAAU,EAAE,CAAC;CAC5B;AAED,qBAAa,UAAU;IACrB,OAAO,CAAC,QAAQ,CAA6B;IAC7C,OAAO,CAAC,QAAQ,CAAa;gBAEjB,MAAM,EAAE,gBAAgB;IAO9B,QAAQ,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,gBAAgB,CAAC;CAuFpE"}

package/dist/dispatch/dispatcher.js

@@ -0,0 +1,84 @@
+/**
+ * Central Dispatcher -- Routes requests through middleware to domain handlers.
+ *
+ * The dispatcher is the single entry point for the CLI adapter.
+ * It resolves operations, validates parameters, runs the middleware pipeline,
+ * and delegates to the appropriate domain handler.
+ *
+ * Flow: DispatchRequest → resolve → param validation → middleware → handler
+ *
+ * @epic T4820
+ */
+import { createDispatchMeta } from './lib/meta.js';
+import { compose } from './middleware/pipeline.js';
+import { resolve, validateRequiredParams } from './registry.js';
+export class Dispatcher {
+    handlers;
+    pipeline;
+    constructor(config) {
+        this.handlers = config.handlers;
+        this.pipeline = config.middlewares?.length
+            ? compose(config.middlewares)
+            : (_req, next) => next();
+    }
+    async dispatch(request) {
+        const startTime = Date.now();
+        // 1. Resolve operation from registry
+        const resolved = resolve(request.gateway, request.domain, request.operation);
+        if (!resolved) {
+            return {
+                meta: createDispatchMeta(request.gateway, request.domain, request.operation, startTime, request.source, request.requestId),
+                success: false,
+                error: {
+                    code: 'E_INVALID_OPERATION',
+                    message: `Unknown operation: ${request.gateway}:${request.domain}.${request.operation}`,
+                },
+            };
+        }
+        // 2. Validate required params
+        const missing = validateRequiredParams(resolved.def, request.params);
+        if (missing.length > 0) {
+            return {
+                meta: createDispatchMeta(request.gateway, resolved.domain, resolved.operation, startTime, request.source, request.requestId),
+                success: false,
+                error: {
+                    code: 'E_MISSING_PARAMS',
+                    message: `Missing required parameters: ${missing.join(', ')}`,
+                    details: { missing },
+                },
+            };
+        }
+        // 3. Look up domain handler
+        const handler = this.handlers.get(resolved.domain);
+        if (!handler) {
+            return {
+                meta: createDispatchMeta(request.gateway, resolved.domain, resolved.operation, startTime, request.source, request.requestId),
+                success: false,
+                error: {
+                    code: 'E_NO_HANDLER',
+                    message: `No handler for domain: ${resolved.domain}`,
+                },
+            };
+        }
+        // 4. Run middleware pipeline with terminal handler
+        const terminal = async () => {
+            if (request.gateway === 'query') {
+                return handler.query(resolved.operation, request.params);
+            }
+            else {
+                return handler.mutate(resolved.operation, request.params);
+            }
+        };
+        const response = await this.pipeline(request, terminal);
+        // 5. Stamp timing and tracing metadata
+        response.meta.duration_ms = Date.now() - startTime;
+        response.meta.requestId = request.requestId;
+        response.meta.source = request.source;
+        // 6. Stamp session identity (T4959)
+        if (request.sessionId) {
+            response.meta.sessionId = request.sessionId;
+        }
+        return response;
+    }
+}
+//# sourceMappingURL=dispatcher.js.map

package/dist/dispatch/dispatcher.js.map

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

package/dist/dispatch/domains/_base.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Shared base helpers for domain handlers.
+ * DRY utility -- extracts the 4 common patterns found in all domain handlers.
+ *
+ * All functions are standalone (not a class) to match the function-based helper style.
+ * Handlers call these instead of re-implementing wrapEngineResult, errorResponse, etc.
+ *
+ * @epic T5671
+ */
+import type { ProblemDetails } from '@cleocode/core';
+import type { DispatchResponse } from '../types.js';
+/**
+ * Engine result shape accepted by wrapResult.
+ * Matches the union of what all engine functions return.
+ */
+export interface EngineResult {
+    success: boolean;
+    data?: unknown;
+    page?: import('@cleocode/lafs').LAFSPage;
+    error?: {
+        code: string;
+        message: string;
+        details?: unknown;
+        exitCode?: number;
+        fix?: string;
+        alternatives?: Array<{
+            action: string;
+            command: string;
+        }>;
+        problemDetails?: ProblemDetails;
+    };
+}
+/**
+ * Wrap a native engine result into a DispatchResponse.
+ * Handles success data, page metadata, and structured errors.
+ */
+export declare function wrapResult(result: EngineResult, gateway: string, domain: string, operation: string, startTime: number): DispatchResponse;
+/**
+ * Return a standard error response.
+ */
+export declare function errorResult(gateway: string, domain: string, operation: string, code: string, message: string, startTime: number): DispatchResponse;
+/**
+ * Return a standard "unsupported operation" error response.
+ */
+export declare function unsupportedOp(gateway: string, domain: string, operation: string, startTime: number): DispatchResponse;
+/**
+ * Extract limit and offset pagination params from a params dict.
+ */
+export declare function getListParams(params?: Record<string, unknown>): {
+    limit?: number;
+    offset?: number;
+};
+/**
+ * Handle a caught error: extract message and return an internal error response.
+ * Callers should log the error themselves (with their domain-specific logger)
+ * before or after calling this.
+ */
+export declare function handleErrorResult(gateway: string, domain: string, operation: string, error: unknown, startTime: number): DispatchResponse;
+//# sourceMappingURL=_base.d.ts.map

package/dist/dispatch/domains/_base.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"_base.d.ts","sourceRoot":"","sources":["../../../src/dispatch/domains/_base.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AACrD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAGpD;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,IAAI,CAAC,EAAE,OAAO,gBAAgB,EAAE,QAAQ,CAAC;IACzC,KAAK,CAAC,EAAE;QACN,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,CAAC;QAChB,OAAO,CAAC,EAAE,OAAO,CAAC;QAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,GAAG,CAAC,EAAE,MAAM,CAAC;QACb,YAAY,CAAC,EAAE,KAAK,CAAC;YAAE,MAAM,EAAE,MAAM,CAAC;YAAC,OAAO,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;QAC1D,cAAc,CAAC,EAAE,cAAc,CAAC;KACjC,CAAC;CACH;AAED;;;GAGG;AACH,wBAAgB,UAAU,CACxB,MAAM,EAAE,YAAY,EACpB,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,GAChB,gBAAgB,CAoBlB;AAED;;GAEG;AACH,wBAAgB,WAAW,CACzB,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,GAChB,gBAAgB,CAMlB;AAED;;GAEG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,GAChB,gBAAgB,CAMlB;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG;IAC/D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAKA;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,OAAO,EACd,SAAS,EAAE,MAAM,GAChB,gBAAgB,CAOlB"}