glirastes 0.3.0 → 0.3.2

package/dist/cjs/react/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/react/ui.d.ts

@@ -0,0 +1,73 @@
+import type { ActionIdRegistry } from '../types.js';
+export interface UiAction {
+    type: string;
+    actionId?: string;
+    [key: string]: unknown;
+}
+export type UiActionHandler = (action: UiAction) => void | Promise<void>;
+export interface AiClientActionEventDetail {
+    actionId: string;
+    payload?: Record<string, unknown>;
+}
+export declare class UiActionBus {
+    private handlersByType;
+    private handlersById;
+    subscribeByType(type: string, handler: UiActionHandler): () => void;
+    subscribeById(actionId: string, handler: UiActionHandler): () => void;
+    dispatch(action: UiAction): Promise<void>;
+}
+export declare function useAiClientActionByType(bus: UiActionBus, actionType: string, handler: UiActionHandler): void;
+export declare function useAiClientActionById(bus: UiActionBus, actionId: string, handler: UiActionHandler): void;
+/**
+ * Set the action ID registry for validation (call once at app startup).
+ * The registry is typically auto-generated by the codegen package.
+ */
+export declare function setActionIdRegistry(registry: ActionIdRegistry): void;
+/**
+ * Dispatch an AI client action via window events.
+ * Used by the chat panel / AI layer to trigger UI updates.
+ */
+export declare function dispatchAiClientAction(detail: AiClientActionEventDetail): void;
+/**
+ * Dispatch one or more AI client actions via window events.
+ * Convenience wrapper for compound actions — accepts a single action or an array.
+ */
+export declare function dispatchAiClientActions(details: AiClientActionEventDetail | AiClientActionEventDetail[]): void;
+/**
+ * Hook to register a handler for a specific AI client action ID.
+ * The handler is tracked in a global registry for dev-mode validation.
+ *
+ * @example
+ * ```tsx
+ * useAiClientAction('task-details.open', (payload) => {
+ *   openTaskDetails(payload?.taskId as string);
+ * });
+ * ```
+ */
+export declare function useAiClientAction(actionId: string, handler: (payload?: Record<string, unknown>) => void): void;
+/**
+ * Returns all currently registered handler actionIds.
+ */
+export declare function getRegisteredHandlers(): string[];
+/**
+ * Returns actionIds defined in the registry but missing a registered handler.
+ * Useful for dev-mode validation to ensure all AI actions have handlers.
+ */
+export declare function getMissingHandlers(): string[];
+/**
+ * Returns info about a specific actionId from the registry.
+ */
+export declare function getActionIdInfo(actionId: string): import("../types.js").ActionIdEntry | undefined;
+/**
+ * Hook that warns about missing AI action handlers in development mode.
+ * Checks after a 2-second delay to allow all components to mount and register.
+ *
+ * @example
+ * ```tsx
+ * // In your AppShell or root layout component:
+ * useAiMissingHandlerWarning();
+ * ```
+ */
+export declare function useAiMissingHandlerWarning(options?: {
+    delay?: number;
+}): void;

package/dist/cjs/react/ui.js

@@ -0,0 +1,183 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UiActionBus = void 0;
+exports.useAiClientActionByType = useAiClientActionByType;
+exports.useAiClientActionById = useAiClientActionById;
+exports.setActionIdRegistry = setActionIdRegistry;
+exports.dispatchAiClientAction = dispatchAiClientAction;
+exports.dispatchAiClientActions = dispatchAiClientActions;
+exports.useAiClientAction = useAiClientAction;
+exports.getRegisteredHandlers = getRegisteredHandlers;
+exports.getMissingHandlers = getMissingHandlers;
+exports.getActionIdInfo = getActionIdInfo;
+exports.useAiMissingHandlerWarning = useAiMissingHandlerWarning;
+const react_1 = require("react");
+// ============================================================================
+// UiActionBus (class-based, framework-agnostic)
+// ============================================================================
+function addHandler(map, key, handler) {
+    const handlers = map.get(key) ?? new Set();
+    handlers.add(handler);
+    map.set(key, handlers);
+    return () => {
+        const current = map.get(key);
+        if (!current)
+            return;
+        current.delete(handler);
+        if (current.size === 0)
+            map.delete(key);
+    };
+}
+class UiActionBus {
+    handlersByType = new Map();
+    handlersById = new Map();
+    subscribeByType(type, handler) {
+        return addHandler(this.handlersByType, type, handler);
+    }
+    subscribeById(actionId, handler) {
+        return addHandler(this.handlersById, actionId, handler);
+    }
+    async dispatch(action) {
+        const typeHandlers = this.handlersByType.get(action.type);
+        const idHandlers = action.actionId
+            ? this.handlersById.get(action.actionId)
+            : undefined;
+        const allHandlers = new Set([
+            ...(typeHandlers ? Array.from(typeHandlers) : []),
+            ...(idHandlers ? Array.from(idHandlers) : []),
+        ]);
+        for (const handler of allHandlers) {
+            await handler(action);
+        }
+    }
+}
+exports.UiActionBus = UiActionBus;
+// ============================================================================
+// UiActionBus Hooks
+// ============================================================================
+function useAiClientActionByType(bus, actionType, handler) {
+    (0, react_1.useEffect)(() => bus.subscribeByType(actionType, handler), [bus, actionType, handler]);
+}
+function useAiClientActionById(bus, actionId, handler) {
+    (0, react_1.useEffect)(() => bus.subscribeById(actionId, handler), [bus, actionId, handler]);
+}
+// ============================================================================
+// Window Event-based Action Dispatch (to-do-manager pattern)
+// ============================================================================
+const AI_CLIENT_ACTION_EVENT = 'ai-client-action';
+/** Global registry of currently registered handler actionIds */
+const registeredHandlers = new Set();
+/** Optional reference to an ActionIdRegistry for validation */
+let actionIdRegistryRef;
+/**
+ * Set the action ID registry for validation (call once at app startup).
+ * The registry is typically auto-generated by the codegen package.
+ */
+function setActionIdRegistry(registry) {
+    actionIdRegistryRef = registry;
+}
+/**
+ * Dispatch an AI client action via window events.
+ * Used by the chat panel / AI layer to trigger UI updates.
+ */
+function dispatchAiClientAction(detail) {
+    if (typeof window === 'undefined')
+        return;
+    window.dispatchEvent(new CustomEvent(AI_CLIENT_ACTION_EVENT, { detail }));
+}
+/**
+ * Dispatch one or more AI client actions via window events.
+ * Convenience wrapper for compound actions — accepts a single action or an array.
+ */
+function dispatchAiClientActions(details) {
+    const actions = Array.isArray(details) ? details : [details];
+    for (const detail of actions) {
+        dispatchAiClientAction(detail);
+    }
+}
+/**
+ * Hook to register a handler for a specific AI client action ID.
+ * The handler is tracked in a global registry for dev-mode validation.
+ *
+ * @example
+ * ```tsx
+ * useAiClientAction('task-details.open', (payload) => {
+ *   openTaskDetails(payload?.taskId as string);
+ * });
+ * ```
+ */
+function useAiClientAction(actionId, handler) {
+    const handlerRef = (0, react_1.useRef)(handler);
+    handlerRef.current = handler;
+    const stableHandler = (0, react_1.useCallback)((payload) => handlerRef.current(payload), []);
+    (0, react_1.useEffect)(() => {
+        registeredHandlers.add(actionId);
+        const handleEvent = (event) => {
+            const detail = event
+                .detail;
+            if (!detail || detail.actionId !== actionId)
+                return;
+            stableHandler(detail.payload);
+        };
+        window.addEventListener(AI_CLIENT_ACTION_EVENT, handleEvent);
+        return () => {
+            window.removeEventListener(AI_CLIENT_ACTION_EVENT, handleEvent);
+            registeredHandlers.delete(actionId);
+        };
+    }, [actionId, stableHandler]);
+}
+// ============================================================================
+// Handler Registry Inspection (for dev-mode validation)
+// ============================================================================
+/**
+ * Returns all currently registered handler actionIds.
+ */
+function getRegisteredHandlers() {
+    return Array.from(registeredHandlers);
+}
+/**
+ * Returns actionIds defined in the registry but missing a registered handler.
+ * Useful for dev-mode validation to ensure all AI actions have handlers.
+ */
+function getMissingHandlers() {
+    if (!actionIdRegistryRef)
+        return [];
+    const required = Object.keys(actionIdRegistryRef);
+    return required.filter((id) => !registeredHandlers.has(id));
+}
+/**
+ * Returns info about a specific actionId from the registry.
+ */
+function getActionIdInfo(actionId) {
+    return actionIdRegistryRef?.[actionId];
+}
+// ============================================================================
+// Dev-Mode Missing Handler Warning
+// ============================================================================
+/**
+ * Hook that warns about missing AI action handlers in development mode.
+ * Checks after a 2-second delay to allow all components to mount and register.
+ *
+ * @example
+ * ```tsx
+ * // In your AppShell or root layout component:
+ * useAiMissingHandlerWarning();
+ * ```
+ */
+function useAiMissingHandlerWarning(options = {}) {
+    const { delay = 2000 } = options;
+    (0, react_1.useEffect)(() => {
+        if (process.env.NODE_ENV !== 'development')
+            return;
+        if (!actionIdRegistryRef)
+            return;
+        const timer = setTimeout(() => {
+            const missing = getMissingHandlers();
+            if (missing.length === 0)
+                return;
+            console.warn(`[glirastes] ${missing.length} AI action handler(s) missing:`, missing);
+            console.warn('[glirastes] Register handlers with useAiClientAction() or mark as @ai-ignore');
+        }, delay);
+        return () => clearTimeout(timer);
+    }, [delay]);
+}

package/dist/cjs/react/utils/create-approval-description.d.ts

@@ -0,0 +1,53 @@
+import type { ApprovalDescriptionFn } from '../types.js';
+export interface ApprovalDescriptionConfig {
+    /** Map field names to human-readable labels. Example: `{ dueDate: 'Due date' }` */
+    fieldLabels?: Record<string, string>;
+    /**
+     * Map of field+value to translated display value.
+     * Outer key = field name, inner key = raw value.
+     *
+     * @example
+     * ```ts
+     * { priority: { high: 'High', low: 'Low' }, status: { done: 'Done' } }
+     * ```
+     */
+    valueTranslations?: Record<string, Record<string, string>>;
+    /** Field names to always hide (e.g. internal IDs). UUIDs are hidden automatically. */
+    hiddenFields?: string[] | Set<string>;
+    /** Map tool names to human-readable action labels */
+    toolLabels?: Record<string, string>;
+    /** Locale for date formatting (default: `'en-US'`) */
+    dateLocale?: string;
+    /** Default confirm button text */
+    defaultConfirmText?: string;
+    /** Default description for unknown tools */
+    defaultDescription?: string;
+}
+/**
+ * Create an approval description generator that formats tool arguments
+ * into human-readable detail lines for approval cards.
+ *
+ * Features:
+ * - Auto-hides UUID values and configurable field names
+ * - Auto-formats ISO dates using the configured locale
+ * - Translates field values via configurable mappings
+ * - Flattens nested objects into detail lines
+ * - Filters empty arrays and null/undefined values
+ *
+ * @example
+ * ```ts
+ * import { createApprovalDescriptionGenerator } from '../index.js';
+ *
+ * const getApprovalDescription = createApprovalDescriptionGenerator({
+ *   fieldLabels: { title: 'Title', dueDate: 'Due date', priority: 'Priority' },
+ *   valueTranslations: { priority: { high: 'High', medium: 'Medium', low: 'Low' } },
+ *   hiddenFields: ['taskId', 'assigneeId', 'groupId'],
+ *   toolLabels: { create_task: 'Create task', update_task: 'Update task' },
+ *   dateLocale: 'de-DE',
+ *   defaultConfirmText: 'Execute',
+ * });
+ *
+ * <AiChatProvider approvalDescription={getApprovalDescription} ... />
+ * ```
+ */
+export declare function createApprovalDescriptionGenerator(config?: ApprovalDescriptionConfig): ApprovalDescriptionFn;

package/dist/cjs/react/utils/create-approval-description.js

@@ -0,0 +1,122 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createApprovalDescriptionGenerator = createApprovalDescriptionGenerator;
+// ============================================================================
+// Helpers
+// ============================================================================
+const UUID_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const ISO_DATE_REGEX = /^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}:\d{2}(\.\d{3})?(Z|[+-]\d{2}:\d{2})?)?$/;
+function capitalize(str) {
+    return str ? str.charAt(0).toUpperCase() + str.slice(1) : str;
+}
+function formatDateValue(strValue, locale) {
+    try {
+        const date = new Date(strValue);
+        if (isNaN(date.getTime()))
+            return strValue;
+        // Date-only (YYYY-MM-DD)
+        if (strValue.length === 10) {
+            return date.toLocaleDateString(locale, { day: '2-digit', month: '2-digit', year: 'numeric' });
+        }
+        return date.toLocaleString(locale, {
+            day: '2-digit', month: '2-digit', year: 'numeric',
+            hour: '2-digit', minute: '2-digit',
+        });
+    }
+    catch {
+        return strValue;
+    }
+}
+// ============================================================================
+// Factory
+// ============================================================================
+/**
+ * Create an approval description generator that formats tool arguments
+ * into human-readable detail lines for approval cards.
+ *
+ * Features:
+ * - Auto-hides UUID values and configurable field names
+ * - Auto-formats ISO dates using the configured locale
+ * - Translates field values via configurable mappings
+ * - Flattens nested objects into detail lines
+ * - Filters empty arrays and null/undefined values
+ *
+ * @example
+ * ```ts
+ * import { createApprovalDescriptionGenerator } from '../index.js';
+ *
+ * const getApprovalDescription = createApprovalDescriptionGenerator({
+ *   fieldLabels: { title: 'Title', dueDate: 'Due date', priority: 'Priority' },
+ *   valueTranslations: { priority: { high: 'High', medium: 'Medium', low: 'Low' } },
+ *   hiddenFields: ['taskId', 'assigneeId', 'groupId'],
+ *   toolLabels: { create_task: 'Create task', update_task: 'Update task' },
+ *   dateLocale: 'de-DE',
+ *   defaultConfirmText: 'Execute',
+ * });
+ *
+ * <AiChatProvider approvalDescription={getApprovalDescription} ... />
+ * ```
+ */
+function createApprovalDescriptionGenerator(config = {}) {
+    const { fieldLabels = {}, valueTranslations = {}, hiddenFields: rawHiddenFields, toolLabels = {}, dateLocale = 'en-US', defaultConfirmText, defaultDescription = 'Confirm action?', } = config;
+    const hiddenFields = rawHiddenFields instanceof Set
+        ? rawHiddenFields
+        : new Set(rawHiddenFields ?? []);
+    function formatValue(key, value) {
+        if (value && typeof value === 'object' && !Array.isArray(value)) {
+            return Object.entries(value)
+                .filter(([, v]) => v !== undefined && v !== null && v !== '')
+                .map(([k, v]) => `${fieldLabels[k] || k}: ${formatValue(k, v)}`)
+                .join(', ');
+        }
+        const strValue = String(value);
+        if (valueTranslations[key]?.[strValue])
+            return valueTranslations[key][strValue];
+        if (ISO_DATE_REGEX.test(strValue))
+            return formatDateValue(strValue, dateLocale);
+        return capitalize(strValue);
+    }
+    function collectDetails(obj) {
+        const result = [];
+        for (const [key, value] of Object.entries(obj)) {
+            if (value === undefined || value === null || value === '')
+                continue;
+            if (hiddenFields.has(key))
+                continue;
+            if (UUID_REGEX.test(String(value)))
+                continue;
+            if (value && typeof value === 'object' && !Array.isArray(value)) {
+                result.push(...collectDetails(value));
+                continue;
+            }
+            const label = fieldLabels[key] || key;
+            let displayValue;
+            if (Array.isArray(value)) {
+                const filtered = value.filter((v) => !UUID_REGEX.test(String(v)));
+                if (filtered.length === 0)
+                    continue;
+                displayValue = filtered.map((v) => formatValue(key, v)).join(', ');
+            }
+            else {
+                displayValue = formatValue(key, value);
+            }
+            result.push(`${label}: ${displayValue}`);
+        }
+        return result;
+    }
+    return (toolName, approvalId, args) => {
+        const details = [];
+        if (args && typeof args === 'object') {
+            details.push(...collectDetails(args));
+        }
+        return {
+            id: approvalId,
+            toolName,
+            args: (args && typeof args === 'object' ? args : {}),
+            messageId: '',
+            description: toolLabels[toolName] || defaultDescription,
+            details,
+            ...(defaultConfirmText ? { confirmText: defaultConfirmText } : {}),
+        };
+    };
+}

package/dist/cjs/react/utils/create-tool-result-handler.d.ts

@@ -0,0 +1,90 @@
+/** Schema-like object that can validate values (compatible with Zod, Valibot, etc.) */
+interface SafeParseable {
+    safeParse(value: unknown): {
+        success: true;
+        data: Record<string, unknown>;
+    } | {
+        success: false;
+        error: {
+            issues: unknown[];
+        };
+    };
+}
+export interface ToolResultHandlerConfig {
+    /** Schema to validate uiActions (compatible with Zod `.safeParse()`). When omitted, uiActions are not validated. */
+    uiActionSchema?: SafeParseable;
+    /**
+     * Custom action handlers by uiAction type.
+     * Called with the full validated uiAction object.
+     *
+     * @example
+     * ```ts
+     * actionHandlers: {
+     *   'set-filters': (action) => {
+     *     window.dispatchEvent(new CustomEvent('ai-set-filters', { detail: action.filters }));
+     *   },
+     * }
+     * ```
+     */
+    actionHandlers?: Record<string, (action: Record<string, unknown>) => void>;
+    /**
+     * Map of entity names to list page destinations.
+     * Used by convention-based `{entity}-created` actions.
+     *
+     * @example `{ task: '/tasks', group: '/groups' }`
+     */
+    entityListDestinations?: Record<string, string>;
+    /** Called when an entity-created or entity-deleted action requires navigation */
+    onNavigate?: (destination: string, entity: string) => void;
+    /** Called when an entity-updated action requires opening a detail view */
+    onOpenDetail?: (entity: string, entityId: string) => void;
+    /** Called for `run-client-action` uiAction types */
+    onClientAction?: (actionId: string, payload?: Record<string, unknown>) => void;
+    /** Called for any successful tool result */
+    onSuccess?: (toolName: string, result: Record<string, unknown>) => void;
+    /**
+     * Fallback handlers for specific tool names.
+     * Called when a tool succeeds but has no uiAction to process.
+     */
+    toolFallbacks?: Record<string, (result: Record<string, unknown>) => void>;
+    /** Optional dedupe guard for duplicate `run-client-action` dispatches. */
+    clientActionDedupe?: {
+        enabled?: boolean;
+        windowMs?: number;
+        actionIds?: string[];
+    };
+}
+/**
+ * Create a tool result handler that processes tool outputs for UI-side actions.
+ *
+ * Extracts `uiAction` from tool results, validates against an optional schema,
+ * and routes to the appropriate handler based on action type.
+ *
+ * Supports convention-based entity actions (`{entity}-created`, `{entity}-updated`,
+ * `{entity}-deleted`), `run-client-action`, and custom action handlers.
+ *
+ * @example
+ * ```ts
+ * import { createToolResultHandler } from '../index.js';
+ * import { dispatchAiClientAction } from '../ui/index.js';
+ *
+ * const handleToolResult = createToolResultHandler({
+ *   uiActionSchema: mySchema,
+ *   entityListDestinations: { task: '/tasks', group: '/groups' },
+ *   onNavigate: (dest) => router.push(dest),
+ *   onOpenDetail: (entity, id) => openPanel(entity, id),
+ *   onClientAction: (actionId, payload) => dispatchAiClientAction({ actionId, payload }),
+ *   onSuccess: () => window.dispatchEvent(new CustomEvent('data-refresh')),
+ *   actionHandlers: {
+ *     'set-filters': (action) => {
+ *       window.dispatchEvent(new CustomEvent('ai-set-filters', { detail: action.filters }));
+ *     },
+ *   },
+ * });
+ *
+ * // Wire into AiChatProvider or use in useEffect:
+ * <AiChatProvider onToolResult={handleToolResult} ... />
+ * ```
+ */
+export declare function createToolResultHandler(config: ToolResultHandlerConfig): (toolName: string, result: unknown) => void;
+export {};