@friggframework/admin-scripts 2.0.0--canary.522.cbd3d5a.0 → 2.0.0--canary.517.21b69ac.0

package/src/application/__tests__/script-runner.test.js

@@ -23,7 +23,7 @@ describe('ScriptRunner', () => {
             config: {
                 timeout: 300000,
                 maxRetries: 0,
-                requiresIntegrationFactory: false,
+                requireIntegrationInstance: false,
             },
         };
 
@@ -36,9 +36,9 @@ describe('ScriptRunner', () => {
         scriptFactory = new ScriptFactory([TestScript]);
 
         mockCommands = {
-            createScriptExecution: jest.fn(),
-            updateScriptExecutionStatus: jest.fn(),
-            completeScriptExecution: jest.fn(),
+            createAdminProcess: jest.fn(),
+            updateAdminProcessState: jest.fn(),
+            completeAdminProcess: jest.fn(),
         };
 
         mockFrigg = {
@@ -49,11 +49,11 @@ describe('ScriptRunner', () => {
         createAdminScriptCommands.mockReturnValue(mockCommands);
         createAdminFriggCommands.mockReturnValue(mockFrigg);
 
-        mockCommands.createScriptExecution.mockResolvedValue({
+        mockCommands.createAdminProcess.mockResolvedValue({
             id: 'exec-123',
         });
-        mockCommands.updateScriptExecutionStatus.mockResolvedValue({});
-        mockCommands.completeScriptExecution.mockResolvedValue({ success: true });
+        mockCommands.updateAdminProcessState.mockResolvedValue({});
+        mockCommands.completeAdminProcess.mockResolvedValue({ success: true });
     });
 
     afterEach(() => {
@@ -76,7 +76,7 @@ describe('ScriptRunner', () => {
             expect(result.executionId).toBe('exec-123');
             expect(result.metrics.durationMs).toBeGreaterThanOrEqual(0);
 
-            expect(mockCommands.createScriptExecution).toHaveBeenCalledWith({
+            expect(mockCommands.createAdminProcess).toHaveBeenCalledWith({
                 scriptName: 'test-script',
                 scriptVersion: '1.0.0',
                 trigger: 'MANUAL',
@@ -85,15 +85,15 @@ describe('ScriptRunner', () => {
                 audit: { apiKeyName: 'test-key' },
             });
 
-            expect(mockCommands.updateScriptExecutionStatus).toHaveBeenCalledWith(
+            expect(mockCommands.updateAdminProcessState).toHaveBeenCalledWith(
                 'exec-123',
                 'RUNNING'
             );
 
-            expect(mockCommands.completeScriptExecution).toHaveBeenCalledWith(
+            expect(mockCommands.completeAdminProcess).toHaveBeenCalledWith(
                 'exec-123',
                 expect.objectContaining({
-                    status: 'COMPLETED',
+                    state: 'COMPLETED',
                     output: { success: true, params: { foo: 'bar' } },
                     metrics: expect.objectContaining({
                         durationMs: expect.any(Number),
@@ -128,10 +128,10 @@ describe('ScriptRunner', () => {
             expect(result.scriptName).toBe('failing-script');
             expect(result.error.message).toBe('Script failed');
 
-            expect(mockCommands.completeScriptExecution).toHaveBeenCalledWith(
+            expect(mockCommands.completeAdminProcess).toHaveBeenCalledWith(
                 'exec-123',
                 expect.objectContaining({
-                    status: 'FAILED',
+                    state: 'FAILED',
                     error: expect.objectContaining({
                         message: 'Script failed',
                     }),
@@ -146,7 +146,7 @@ describe('ScriptRunner', () => {
                     version: '1.0.0',
                     description: 'Integration script',
                     config: {
-                        requiresIntegrationFactory: true,
+                        requireIntegrationInstance: true,
                     },
                 };
 
@@ -178,14 +178,144 @@ describe('ScriptRunner', () => {
             });
 
             expect(result.executionId).toBe('existing-exec-456');
-            expect(mockCommands.createScriptExecution).not.toHaveBeenCalled();
-            expect(mockCommands.updateScriptExecutionStatus).toHaveBeenCalledWith(
+            expect(mockCommands.createAdminProcess).not.toHaveBeenCalled();
+            expect(mockCommands.updateAdminProcessState).toHaveBeenCalledWith(
                 'existing-exec-456',
                 'RUNNING'
             );
         });
     });
 
+    describe('dry-run mode', () => {
+        it('should return preview without executing script', async () => {
+            const runner = new ScriptRunner({ scriptFactory, commands: mockCommands });
+
+            const result = await runner.execute('test-script', { foo: 'bar' }, {
+                trigger: 'MANUAL',
+                dryRun: true,
+            });
+
+            expect(result.dryRun).toBe(true);
+            expect(result.status).toBe('DRY_RUN_VALID');
+            expect(result.scriptName).toBe('test-script');
+            expect(result.preview.script.name).toBe('test-script');
+            expect(result.preview.script.version).toBe('1.0.0');
+            expect(result.preview.input).toEqual({ foo: 'bar' });
+            expect(result.message).toContain('validation passed');
+
+            // Should NOT create execution record or call commands
+            expect(mockCommands.createAdminProcess).not.toHaveBeenCalled();
+            expect(mockCommands.updateAdminProcessState).not.toHaveBeenCalled();
+            expect(mockCommands.completeAdminProcess).not.toHaveBeenCalled();
+        });
+
+        it('should validate required parameters in dry-run', async () => {
+            class SchemaScript extends AdminScriptBase {
+                static Definition = {
+                    name: 'schema-script',
+                    version: '1.0.0',
+                    description: 'Script with schema',
+                    inputSchema: {
+                        type: 'object',
+                        required: ['requiredParam'],
+                        properties: {
+                            requiredParam: { type: 'string' },
+                            optionalParam: { type: 'number' },
+                        },
+                    },
+                };
+
+                async execute() {
+                    return {};
+                }
+            }
+
+            scriptFactory.register(SchemaScript);
+            const runner = new ScriptRunner({ scriptFactory, commands: mockCommands });
+
+            // Missing required parameter
+            const result = await runner.execute('schema-script', {}, {
+                dryRun: true,
+            });
+
+            expect(result.status).toBe('DRY_RUN_INVALID');
+            expect(result.preview.validation.valid).toBe(false);
+            expect(result.preview.validation.errors).toContain('Missing required parameter: requiredParam');
+        });
+
+        it('should validate parameter types in dry-run', async () => {
+            class TypedScript extends AdminScriptBase {
+                static Definition = {
+                    name: 'typed-script',
+                    version: '1.0.0',
+                    description: 'Script with typed params',
+                    inputSchema: {
+                        type: 'object',
+                        properties: {
+                            count: { type: 'integer' },
+                            name: { type: 'string' },
+                            enabled: { type: 'boolean' },
+                        },
+                    },
+                };
+
+                async execute() {
+                    return {};
+                }
+            }
+
+            scriptFactory.register(TypedScript);
+            const runner = new ScriptRunner({ scriptFactory, commands: mockCommands });
+
+            const result = await runner.execute('typed-script', {
+                count: 'not-a-number',
+                name: 123,
+                enabled: 'true',
+            }, {
+                dryRun: true,
+            });
+
+            expect(result.status).toBe('DRY_RUN_INVALID');
+            expect(result.preview.validation.errors).toHaveLength(3);
+        });
+
+        it('should pass validation with correct parameters', async () => {
+            class ValidScript extends AdminScriptBase {
+                static Definition = {
+                    name: 'valid-script',
+                    version: '1.0.0',
+                    description: 'Script for validation',
+                    inputSchema: {
+                        type: 'object',
+                        required: ['name'],
+                        properties: {
+                            name: { type: 'string' },
+                            count: { type: 'integer' },
+                        },
+                    },
+                };
+
+                async execute() {
+                    return {};
+                }
+            }
+
+            scriptFactory.register(ValidScript);
+            const runner = new ScriptRunner({ scriptFactory, commands: mockCommands });
+
+            const result = await runner.execute('valid-script', {
+                name: 'test',
+                count: 42,
+            }, {
+                dryRun: true,
+            });
+
+            expect(result.status).toBe('DRY_RUN_VALID');
+            expect(result.preview.validation.valid).toBe(true);
+            expect(result.preview.validation.errors).toHaveLength(0);
+        });
+    });
+
     describe('createScriptRunner()', () => {
         it('should create runner with default factory', () => {
             const runner = createScriptRunner();

package/src/application/admin-frigg-commands.js

@@ -1,18 +1,6 @@
 const { QueuerUtil } = require('@friggframework/core/queues');
 
-/**
- * AdminFriggCommands
- *
- * Helper API for admin scripts. Provides:
- * - Database access via repositories
- * - Integration instantiation (optional)
- * - Logging utilities
- * - Queue operations for self-queuing pattern
- *
- * Follows lazy-loading pattern for repositories to avoid circular dependencies
- * and unnecessary initialization.
- */
-class AdminFriggCommands {
+class AdminScriptContext {
     constructor(params = {}) {
         this.executionId = params.executionId || null;
         this.logs = [];
@@ -25,7 +13,7 @@ class AdminFriggCommands {
         this._userRepository = null;
         this._moduleRepository = null;
         this._credentialRepository = null;
-        this._scriptExecutionRepository = null;
+        this._adminProcessRepository = null;
     }
 
     // ==================== LAZY-LOADED REPOSITORIES ====================
@@ -62,12 +50,12 @@ class AdminFriggCommands {
         return this._credentialRepository;
     }
 
-    get scriptExecutionRepository() {
-        if (!this._scriptExecutionRepository) {
-            const { createScriptExecutionRepository } = require('@friggframework/core/admin-scripts/repositories/script-execution-repository-factory');
-            this._scriptExecutionRepository = createScriptExecutionRepository();
+    get adminProcessRepository() {
+        if (!this._adminProcessRepository) {
+            const { createAdminProcessRepository } = require('@friggframework/core/admin-scripts/repositories/admin-process-repository-factory');
+            this._adminProcessRepository = createAdminProcessRepository();
         }
-        return this._scriptExecutionRepository;
+        return this._adminProcessRepository;
     }
 
     // ==================== INTEGRATION QUERIES ====================
@@ -142,7 +130,7 @@ class AdminFriggCommands {
         if (!this.integrationFactory) {
             throw new Error(
                 'instantiate() requires integrationFactory. ' +
-                'Set Definition.config.requiresIntegrationFactory = true'
+                'Set Definition.config.requireIntegrationInstance = true'
             );
         }
         return this.integrationFactory.getInstanceFromIntegrationId({
@@ -151,12 +139,8 @@ class AdminFriggCommands {
         });
     }
 
-    // ==================== QUEUE OPERATIONS (Self-Queuing Pattern) ====================
+    // ==================== QUEUE OPERATIONS ====================
 
-    /**
-     * Queue a script for execution
-     * Used for self-queuing pattern with long-running scripts
-     */
     async queueScript(scriptName, params = {}) {
         const queueUrl = process.env.ADMIN_SCRIPT_QUEUE_URL;
         if (!queueUrl) {
@@ -176,9 +160,6 @@ class AdminFriggCommands {
         this.log('info', `Queued continuation for ${scriptName}`, { params });
     }
 
-    /**
-     * Queue multiple scripts in a batch
-     */
     async queueScriptBatch(entries) {
         const queueUrl = process.env.ADMIN_SCRIPT_QUEUE_URL;
         if (!queueUrl) {
@@ -209,7 +190,7 @@ class AdminFriggCommands {
 
         // Persist to execution record if we have an executionId
         if (this.executionId) {
-            this.scriptExecutionRepository.appendExecutionLog(this.executionId, entry)
+            this.adminProcessRepository.appendProcessLog(this.executionId, entry)
                 .catch(err => console.error('Failed to persist log:', err));
         }
 
@@ -230,13 +211,20 @@ class AdminFriggCommands {
 }
 
 /**
- * Create AdminFriggCommands instance
+ * Create AdminScriptContext instance
  */
-function createAdminFriggCommands(params = {}) {
-    return new AdminFriggCommands(params);
+function createAdminScriptContext(params = {}) {
+    return new AdminScriptContext(params);
 }
 
+// Legacy aliases for backwards compatibility
+const AdminFriggCommands = AdminScriptContext;
+const createAdminFriggCommands = createAdminScriptContext;
+
 module.exports = {
+    AdminScriptContext,
+    createAdminScriptContext,
+    // Legacy exports (deprecated)
     AdminFriggCommands,
     createAdminFriggCommands,
 };

package/src/application/admin-script-base.js

@@ -1,64 +1,27 @@
-const { createScriptExecutionRepository } = require('@friggframework/core/admin-scripts/repositories/script-execution-repository-factory');
-const { createAdminApiKeyRepository } = require('@friggframework/core/admin-scripts/repositories/admin-api-key-repository-factory');
-
-/**
- * Admin Script Base Class
- *
- * Base class for all admin scripts. Provides:
- * - Standard script definition pattern
- * - Repository access
- * - Logging helpers
- * - Integration factory support (optional)
- *
- * Usage:
- * ```javascript
- * class MyScript extends AdminScriptBase {
- *   static Definition = {
- *     name: 'my-script',
- *     version: '1.0.0',
- *     description: 'Does something useful',
- *     ...
- *   };
- *
- *   async execute(frigg, params) {
- *     // Your script logic here
- *   }
- * }
- * ```
- */
 class AdminScriptBase {
-    /**
-     * CHILDREN SHOULD SPECIFY A DEFINITION FOR THE SCRIPT
-     * Pattern matches IntegrationBase.Definition
-     */
     static Definition = {
-        name: 'Script Name', // Required: unique identifier
-        version: '0.0.0', // Required: semver for migrations
-        description: 'What this script does', // Required: human-readable
-
-        // Script-specific properties
+        name: 'Script Name',
+        version: '0.0.0',
+        description: 'What this script does',
         source: 'USER_DEFINED', // 'BUILTIN' | 'USER_DEFINED'
 
-        inputSchema: null, // Optional: JSON Schema for params
-        outputSchema: null, // Optional: JSON Schema for results
+        inputSchema: null,
+        outputSchema: null,
 
         schedule: {
-            // Optional: Phase 2
             enabled: false,
-            cronExpression: null, // 'cron(0 12 * * ? *)'
+            cronExpression: null,
         },
 
         config: {
-            timeout: 300000, // Default 5 min (ms)
+            timeout: 300000,
             maxRetries: 0,
-            requiresIntegrationFactory: false, // Hint: does script need to instantiate integrations?
+            requireIntegrationInstance: false,
         },
 
         display: {
-            // For future UI
-            label: 'Script Name',
-            description: '',
-            category: 'maintenance', // 'maintenance' | 'healing' | 'sync' | 'custom'
+            category: 'maintenance',
+            icon: null,
         },
     };
 
@@ -74,64 +37,22 @@ class AdminScriptBase {
         return this.Definition;
     }
 
-    /**
-     * Constructor receives dependencies
-     * Pattern matches IntegrationBase constructor
-     */
-    constructor(params = {}) {
-        this.executionId = params.executionId || null;
-        this.logs = [];
-        this._startTime = null;
-
-        // OPTIONAL: Integration factory for scripts that need it
-        this.integrationFactory = params.integrationFactory || null;
-
-        // OPTIONAL: Injected repositories (for testing or custom implementations)
-        this.scriptExecutionRepository = params.scriptExecutionRepository || null;
-        this.adminApiKeyRepository = params.adminApiKeyRepository || null;
-    }
-
-    /**
-     * CHILDREN MUST IMPLEMENT THIS METHOD
-     * @param {AdminFriggCommands} frigg - Helper commands object
-     * @param {Object} params - Script parameters (validated against inputSchema)
-     * @returns {Promise<Object>} - Script results (validated against outputSchema)
-     */
-    async execute(frigg, params) {
-        throw new Error('AdminScriptBase.execute() must be implemented by subclass');
+    static getDisplayLabel() {
+        return this.Definition.display?.label || this.Definition.name;
     }
 
-    /**
-     * Logging helper
-     * @param {string} level - Log level (info, warn, error, debug)
-     * @param {string} message - Log message
-     * @param {Object} data - Additional data
-     * @returns {Object} Log entry
-     */
-    log(level, message, data = {}) {
-        const entry = {
-            level,
-            message,
-            data,
-            timestamp: new Date().toISOString(),
-        };
-        this.logs.push(entry);
-        return entry;
+    static getDisplayDescription() {
+        return this.Definition.display?.description || this.Definition.description;
     }
 
-    /**
-     * Get all logs
-     * @returns {Array} Log entries
-     */
-    getLogs() {
-        return this.logs;
+    constructor(params = {}) {
+        this.context = params.context || null;
+        this.executionId = params.executionId || null;
+        this.integrationFactory = params.integrationFactory || null;
     }
 
-    /**
-     * Clear all logs
-     */
-    clearLogs() {
-        this.logs = [];
+    async execute(params) {
+        throw new Error('AdminScriptBase.execute() must be implemented by subclass');
     }
 }