@supernal/interface 1.0.0

package/dist/cjs/src/decorators/SpecializedTools.js

@@ -0,0 +1,386 @@
+"use strict";
+/**
+ * Specialized Tool Decorators
+ *
+ * Simplified, context-specific decorators that reduce boilerplate by providing
+ * sensible defaults for different use cases.
+ *
+ * DRY Principle: All specialized decorators inherit from base Tool decorator
+ * with context-specific overrides.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SpecializedTools = exports.OnboardingAndTestTool = exports.AIAndTestTool = exports.NavigationTool = exports.DataWriteTool = exports.DataReadTool = exports.OnboardingTool = exports.TestTool = exports.DestructiveTool = exports.DangerousTool = exports.AITool = void 0;
+const Tool_1 = require("./Tool");
+const types_1 = require("../types");
+const ToolPreset_1 = require("./ToolPreset");
+/**
+ * Base function to create specialized tool decorators
+ * DRY: All specialized decorators use this factory
+ *
+ * Merge order (highest priority first):
+ * 1. User config (explicit overrides)
+ * 2. Preset config (class-level @ToolPreset) - applied retroactively
+ * 3. Specialized defaults (from decorator type)
+ * 4. Base defaults (from Tool decorator)
+ */
+function createSpecializedTool(defaults) {
+    return function (config = {}) {
+        // Return decorator function that can access target
+        return function (target, propertyKey, descriptor) {
+            // Get preset if available (only for class methods)
+            // Note: Preset might not be registered yet due to decorator execution order
+            const preset = propertyKey ? (0, ToolPreset_1.applyPreset)(target, {}) : {};
+            // Merge with correct priority:
+            // config (user) > preset > defaults (specialized)
+            const mergedConfig = {
+                ...defaults, // Specialized defaults (lowest priority)
+                ...preset, // Preset (middle priority) - might be empty initially
+                ...config, // User config (highest priority)
+                // Deep merge nested objects
+                permissions: {
+                    ...defaults.permissions,
+                    ...preset.permissions,
+                    ...config.permissions,
+                },
+                callbacks: {
+                    ...defaults.callbacks,
+                    ...preset.callbacks,
+                    ...config.callbacks,
+                },
+                origin: {
+                    ...defaults.origin,
+                    ...preset.origin,
+                    ...config.origin,
+                },
+            };
+            // Apply the base Tool decorator
+            const result = (0, Tool_1.Tool)(mergedConfig)(target, propertyKey, descriptor);
+            // Register this tool as pending preset application (for class methods only)
+            if (propertyKey) {
+                const className = target.constructor?.name || 'Unknown';
+                const methodName = String(propertyKey);
+                const toolId = `${className}.${methodName}`;
+                (0, ToolPreset_1.registerPendingPreset)(className, toolId, config); // Pass user config
+            }
+            return result;
+        };
+    };
+}
+// ============================================================================
+// AI-Enabled Tools
+// ============================================================================
+/**
+ * @AITool - Tools that AI can safely use
+ *
+ * Default Configuration:
+ * - aiEnabled: true
+ * - toolType: 'ai-safe'
+ * - dangerLevel: 'safe'
+ * - requiresApproval: false
+ * - generateSimulation: true
+ * - generateStories: true
+ *
+ * @example
+ * ```typescript
+ * @AITool({ toolId: 'search-button' })
+ * async search(query: string) {
+ *   return await api.search(query);
+ * }
+ * ```
+ */
+exports.AITool = createSpecializedTool({
+    aiEnabled: true,
+    toolType: 'ai-safe',
+    dangerLevel: 'safe',
+    requiresApproval: false,
+    generateSimulation: true,
+    generateStories: true,
+    permissions: {
+        level: 'auto_approve',
+        sensitiveDataAccess: false,
+        networkAccess: false,
+    },
+});
+/**
+ * @DangerousTool - Tools that require approval before AI can use
+ *
+ * Default Configuration:
+ * - aiEnabled: true (but requires approval)
+ * - toolType: 'ai-dangerous'
+ * - dangerLevel: 'dangerous'
+ * - requiresApproval: true
+ * - generateSimulation: true
+ * - generateStories: true
+ *
+ * @example
+ * ```typescript
+ * @DangerousTool({
+ *   toolId: 'delete-account',
+ *   description: 'Permanently delete user account'
+ * })
+ * async deleteAccount(userId: string) {
+ *   return await api.deleteAccount(userId);
+ * }
+ * ```
+ */
+exports.DangerousTool = createSpecializedTool({
+    aiEnabled: true,
+    toolType: 'ai-dangerous',
+    dangerLevel: 'dangerous',
+    requiresApproval: true,
+    generateSimulation: true,
+    generateStories: true,
+    permissions: {
+        level: 'approve_once',
+        sensitiveDataAccess: true,
+        networkAccess: true,
+    },
+});
+/**
+ * @DestructiveTool - Tools for irreversible, destructive operations
+ *
+ * Default Configuration:
+ * - aiEnabled: true (but requires approval)
+ * - toolType: 'ai-dangerous'
+ * - dangerLevel: 'destructive'
+ * - requiresApproval: true
+ * - generateSimulation: true
+ * - generateStories: true
+ *
+ * @example
+ * ```typescript
+ * @DestructiveTool({
+ *   toolId: 'purge-database',
+ *   description: 'Delete all data - cannot be undone'
+ * })
+ * async purgeDatabase() {
+ *   return await api.purgeAllData();
+ * }
+ * ```
+ */
+exports.DestructiveTool = createSpecializedTool({
+    aiEnabled: true,
+    toolType: 'ai-dangerous',
+    dangerLevel: 'destructive',
+    requiresApproval: true,
+    generateSimulation: true,
+    generateStories: true,
+    permissions: {
+        level: 'approve_once',
+        sensitiveDataAccess: true,
+        networkAccess: true,
+    },
+});
+// ============================================================================
+// Testing Tools
+// ============================================================================
+/**
+ * @TestTool - Tools exclusively for testing (AI cannot use)
+ *
+ * Default Configuration:
+ * - aiEnabled: false
+ * - toolType: 'test-only'
+ * - dangerLevel: 'safe'
+ * - requiresApproval: false
+ * - generateSimulation: true
+ * - generateStories: true
+ *
+ * @example
+ * ```typescript
+ * @TestTool({ toolId: 'test-helper' })
+ * async seedTestData() {
+ *   return await db.seedTestData();
+ * }
+ * ```
+ */
+exports.TestTool = createSpecializedTool({
+    aiEnabled: false,
+    toolType: 'test-only',
+    dangerLevel: 'safe',
+    requiresApproval: false,
+    generateSimulation: true,
+    generateStories: true,
+});
+// ============================================================================
+// Onboarding & Help Tools
+// ============================================================================
+/**
+ * @OnboardingTool - Tools for user tutorials and feature tours
+ *
+ * Default Configuration:
+ * - aiEnabled: true
+ * - toolType: 'ai-safe'
+ * - dangerLevel: 'safe'
+ * - requiresApproval: false
+ * - generateSimulation: true
+ * - generateStories: true (critical for onboarding flows)
+ * - category: ToolCategory.ONBOARDING
+ *
+ * @example
+ * ```typescript
+ * @OnboardingTool({
+ *   toolId: 'show-tooltip',
+ *   description: 'Display contextual help tooltip'
+ * })
+ * async showTooltip(elementId: string, message: string) {
+ *   return showTooltip(elementId, message);
+ * }
+ * ```
+ */
+exports.OnboardingTool = createSpecializedTool({
+    aiEnabled: true,
+    toolType: 'ai-safe',
+    dangerLevel: 'safe',
+    requiresApproval: false,
+    generateSimulation: true,
+    generateStories: true, // Critical for onboarding flows
+    category: types_1.ToolCategory.ONBOARDING,
+});
+// ============================================================================
+// Data Tools
+// ============================================================================
+/**
+ * @DataReadTool - Safe read-only data access tools
+ *
+ * Default Configuration:
+ * - aiEnabled: true
+ * - toolType: 'ai-safe'
+ * - dangerLevel: 'safe'
+ * - requiresApproval: false
+ * - category: ToolCategory.DATA
+ *
+ * @example
+ * ```typescript
+ * @DataReadTool({ toolId: 'fetch-users' })
+ * async fetchUsers(filters: UserFilters) {
+ *   return await api.getUsers(filters);
+ * }
+ * ```
+ */
+exports.DataReadTool = createSpecializedTool({
+    aiEnabled: true,
+    toolType: 'ai-safe',
+    dangerLevel: 'safe',
+    requiresApproval: false,
+    category: types_1.ToolCategory.DATA,
+    permissions: {
+        level: 'auto_approve',
+        sensitiveDataAccess: false,
+        networkAccess: true,
+    },
+});
+/**
+ * @DataWriteTool - Tools that create/update data (requires approval)
+ *
+ * Default Configuration:
+ * - aiEnabled: true
+ * - toolType: 'ai-restricted'
+ * - dangerLevel: 'moderate'
+ * - requiresApproval: true
+ * - category: ToolCategory.DATA
+ *
+ * @example
+ * ```typescript
+ * @DataWriteTool({ toolId: 'update-profile' })
+ * async updateProfile(userId: string, data: ProfileData) {
+ *   return await api.updateUser(userId, data);
+ * }
+ * ```
+ */
+exports.DataWriteTool = createSpecializedTool({
+    aiEnabled: true,
+    toolType: 'ai-restricted',
+    dangerLevel: 'moderate',
+    requiresApproval: true,
+    category: types_1.ToolCategory.DATA,
+    permissions: {
+        level: 'approve_once',
+        sensitiveDataAccess: true,
+        networkAccess: true,
+    },
+});
+// ============================================================================
+// Navigation Tools
+// ============================================================================
+/**
+ * @NavigationTool - Tools for page/view navigation
+ *
+ * Default Configuration:
+ * - aiEnabled: true
+ * - toolType: 'ai-safe'
+ * - dangerLevel: 'safe'
+ * - requiresApproval: false
+ * - category: ToolCategory.NAVIGATION
+ * - executionContext: 'ui'
+ *
+ * @example
+ * ```typescript
+ * @NavigationTool({ toolId: 'goto-settings' })
+ * async goToSettings() {
+ *   router.push('/settings');
+ * }
+ * ```
+ */
+exports.NavigationTool = createSpecializedTool({
+    aiEnabled: true,
+    toolType: 'ai-safe',
+    dangerLevel: 'safe',
+    requiresApproval: false,
+    category: types_1.ToolCategory.NAVIGATION,
+    executionContext: 'ui',
+    callbacks: {
+        navigation: true,
+    },
+});
+// ============================================================================
+// Combined Tools (Multiple Contexts)
+// ============================================================================
+/**
+ * @AIAndTestTool - Tools for both AI use and testing
+ *
+ * Default Configuration:
+ * - aiEnabled: true
+ * - toolType: 'ai-safe'
+ * - dangerLevel: 'safe'
+ * - requiresApproval: false
+ * - generateSimulation: true
+ * - generateStories: true
+ *
+ * @example
+ * ```typescript
+ * @AIAndTestTool({ toolId: 'search' })
+ * async search(query: string) {
+ *   return await api.search(query);
+ * }
+ * ```
+ */
+exports.AIAndTestTool = createSpecializedTool({
+    aiEnabled: true,
+    toolType: 'ai-safe',
+    dangerLevel: 'safe',
+    requiresApproval: false,
+    generateSimulation: true,
+    generateStories: true,
+});
+/**
+ * @OnboardingAndTestTool - Tools for onboarding flows and testing
+ *
+ * Alias for OnboardingTool (they have the same config)
+ */
+exports.OnboardingAndTestTool = exports.OnboardingTool;
+// ============================================================================
+// Export all specialized decorators
+// ============================================================================
+exports.SpecializedTools = {
+    AITool: exports.AITool,
+    DangerousTool: exports.DangerousTool,
+    DestructiveTool: exports.DestructiveTool,
+    TestTool: exports.TestTool,
+    OnboardingTool: exports.OnboardingTool,
+    DataReadTool: exports.DataReadTool,
+    DataWriteTool: exports.DataWriteTool,
+    NavigationTool: exports.NavigationTool,
+    AIAndTestTool: exports.AIAndTestTool,
+    OnboardingAndTestTool: exports.OnboardingAndTestTool,
+};
+//# sourceMappingURL=SpecializedTools.js.map

package/dist/cjs/src/decorators/SpecializedTools.js.map

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