glirastes 0.1.0

package/dist/react/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/react/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/react/types.ts"],"names":[],"mappings":""}

package/dist/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/react/ui.js

@@ -0,0 +1,170 @@
+import { useEffect, useCallback, useRef } from '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);
+    };
+}
+export 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);
+        }
+    }
+}
+// ============================================================================
+// UiActionBus Hooks
+// ============================================================================
+export function useAiClientActionByType(bus, actionType, handler) {
+    useEffect(() => bus.subscribeByType(actionType, handler), [bus, actionType, handler]);
+}
+export function useAiClientActionById(bus, actionId, handler) {
+    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.
+ */
+export function setActionIdRegistry(registry) {
+    actionIdRegistryRef = registry;
+}
+/**
+ * Dispatch an AI client action via window events.
+ * Used by the chat panel / AI layer to trigger UI updates.
+ */
+export 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.
+ */
+export 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);
+ * });
+ * ```
+ */
+export function useAiClientAction(actionId, handler) {
+    const handlerRef = useRef(handler);
+    handlerRef.current = handler;
+    const stableHandler = useCallback((payload) => handlerRef.current(payload), []);
+    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.
+ */
+export 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.
+ */
+export 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.
+ */
+export 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();
+ * ```
+ */
+export function useAiMissingHandlerWarning(options = {}) {
+    const { delay = 2000 } = options;
+    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]);
+}
+//# sourceMappingURL=ui.js.map

package/dist/react/ui.js.map

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

package/dist/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/react/utils/create-approval-description.js

@@ -0,0 +1,120 @@
+// ============================================================================
+// 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} ... />
+ * ```
+ */
+export 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 } : {}),
+        };
+    };
+}
+//# sourceMappingURL=create-approval-description.js.map

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

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

package/dist/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 {};