@friggframework/admin-scripts 2.0.0--canary.517.095e3f6.0 → 2.0.0--canary.517.06fe141.0

package/README.md

@@ -1,6 +1,6 @@
 # @friggframework/admin-scripts
 
-Admin Script Runner for Frigg — write and run operational/maintenance scripts inside your deployed Frigg app, with VPC/KMS-secured database access, the same repositories your integrations use, sync or async (queued) execution, dry-run validation, and optional cron scheduling via AWS EventBridge Scheduler.
+Admin Script Runner for Frigg — write and run operational/maintenance scripts inside your deployed Frigg app, with VPC/KMS-secured database access through the same Frigg commands your integrations use, sync or async (queued) execution, dry-run validation, and optional cron scheduling via AWS EventBridge Scheduler.
 
 Typical use cases:
 
@@ -8,7 +8,7 @@ Typical use cases:
 -   **Recurring maintenance** — refresh webhooks/subscriptions before they expire.
 -   **Built-in utilities** — OAuth token refresh, integration health checks.
 
-> Admin scripts are a **high-privilege** surface. Every endpoint is protected by an admin API key (`x-frigg-admin-api-key`), scripts run in your private VPC subnets, and every execution is tracked in the `AdminProcess` table. Never expose the admin API key to browsers or end users.
+> Admin scripts are a **high-privilege** surface. Every endpoint is protected by an admin API key (`x-frigg-admin-api-key`), scripts run in your private VPC subnets, and every execution is tracked in the `AdminScriptExecution` table. Never expose the admin API key to browsers or end users.
 
 ---
 
@@ -87,12 +87,17 @@ class AttioHealingScript extends AdminScriptBase {
 
         this.context.log('info', 'Starting Attio healing', { integrationId });
 
+        // Read persisted data through Frigg commands (never repositories).
+        // Commands return the data on success, or an { error, reason } object
+        // on failure — check `.error` yourself.
         const integration =
-            await this.context.integrationRepository.findIntegrationById(
+            await this.context.commands.integrations.findIntegrationById(
                 integrationId
             );
-        if (!integration) {
-            throw new Error(`Integration ${integrationId} not found`);
+        if (integration.error) {
+            throw new Error(
+                `Integration ${integrationId} not found: ${integration.reason}`
+            );
         }
 
         // Call the live integration when you need to hit an external API.
@@ -117,16 +122,16 @@ module.exports = { AttioHealingScript };
 | Member                       | Description                                                                                                                    |
 | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
 | `log(level, message, data?)` | Records a structured log entry (`level`: `debug`/`info`/`warn`/`error`). Logs are persisted to the execution's `results.logs`. |
-| `integrationRepository`      | Read/query integrations.                                                                                                       |
-| `userRepository`             | Read/query users.                                                                                                              |
-| `moduleRepository`           | Read/query modules.                                                                                                            |
-| `credentialRepository`       | Read credentials (decrypted transparently).                                                                                    |
+| `commands.users`             | User commands (`findIndividualUserById`, `createUser`, `updateUser`, …).                                                       |
+| `commands.credentials`       | Credential commands (`findCredential`, `updateCredential`, …); secrets decrypted transparently.                               |
+| `commands.entities`          | Entity/module commands (`findEntityById`, `findEntitiesByUserId`, …).                                                          |
+| `commands.integrations`      | Integration reads (`findIntegrationById`, `listIntegrations({ type, status })`).                                               |
 | `instantiate(integrationId)` | Returns a hydrated integration instance for calling external APIs. Requires `config.requireIntegrationInstance: true`.         |
 | `queueScript(name, params?)` | Enqueue another script as a follow-up (tracked as a child of the current execution).                                           |
 | `queueScriptBatch(entries)`  | Enqueue many follow-up scripts at once.                                                                                        |
-| `getExecutionId()`           | The current `AdminProcess` record id.                                                                                          |
+| `getExecutionId()`           | The current `AdminScriptExecution` record id.                                                                                  |
 
-Repositories return **plain, decrypted data** — field-level encryption is handled transparently.
+Commands return **plain, decrypted data** on success (field-level encryption is handled transparently) or an `{ error, reason, code }` object on failure — scripts check `.error` themselves. Scripts have no direct repository access; all database interaction goes through the command layer.
 
 ---
 
@@ -242,7 +247,7 @@ async execute(params) {
 -   **Sync** (`mode: 'sync'`) — runs in the API Lambda, result returned in the response. Capped by the API timeout.
 -   **Async** (`mode: 'async'`, default) — queued to SQS and run by the worker Lambda (15-min budget). The SQS queue has a redrive policy (up to 3 receives) to a dead-letter queue, so a crashed invocation is retried at the infrastructure level. There is no application-level per-script retry — model idempotency accordingly.
 
-Every execution is persisted as an `AdminProcess` record with its `state` (`PENDING` → `RUNNING` → `COMPLETED`/`FAILED`), input, output, metrics, and logs.
+Every execution is persisted as an `AdminScriptExecution` record with its `state` (`PENDING` → `RUNNING` → `COMPLETED`/`FAILED`), input, output, metrics, and logs.
 
 ---
 

package/package.json

@@ -1,19 +1,19 @@
 {
     "name": "@friggframework/admin-scripts",
     "prettier": "@friggframework/prettier-config",
-    "version": "2.0.0--canary.517.095e3f6.0",
+    "version": "2.0.0--canary.517.06fe141.0",
     "description": "Admin Script Runner for Frigg - Execute maintenance and operational scripts in hosted environments",
     "dependencies": {
         "@aws-sdk/client-scheduler": "^3.588.0",
-        "@friggframework/core": "2.0.0--canary.517.095e3f6.0",
+        "@friggframework/core": "2.0.0--canary.517.06fe141.0",
         "@hapi/boom": "^10.0.1",
         "express": "^4.18.2",
         "serverless-http": "^3.2.0"
     },
     "devDependencies": {
-        "@friggframework/eslint-config": "2.0.0--canary.517.095e3f6.0",
-        "@friggframework/prettier-config": "2.0.0--canary.517.095e3f6.0",
-        "@friggframework/test": "2.0.0--canary.517.095e3f6.0",
+        "@friggframework/eslint-config": "2.0.0--canary.517.06fe141.0",
+        "@friggframework/prettier-config": "2.0.0--canary.517.06fe141.0",
+        "@friggframework/test": "2.0.0--canary.517.06fe141.0",
         "eslint": "^8.22.0",
         "jest": "^29.7.0",
         "prettier": "^2.7.1",
@@ -44,5 +44,5 @@
         "maintenance",
         "operations"
     ],
-    "gitHead": "095e3f64ffc59fd7afc713a537c69a0ec48eef7b"
+    "gitHead": "06fe14103a72028ce7bf622631580fb24a4abaaf"
 }

package/src/application/__tests__/admin-script-context.test.js

@@ -1,80 +1,24 @@
+const fs = require('fs');
+const path = require('path');
 const {
     AdminScriptContext,
     createAdminScriptContext,
 } = require('../admin-script-context');
 
-// Mock all repository factories
-jest.mock(
-    '@friggframework/core/integrations/repositories/integration-repository-factory'
-);
-jest.mock('@friggframework/core/user/repositories/user-repository-factory');
-jest.mock(
-    '@friggframework/core/modules/repositories/module-repository-factory'
-);
-jest.mock(
-    '@friggframework/core/credential/repositories/credential-repository-factory'
-);
 jest.mock('@friggframework/core/queues');
 
 describe('AdminScriptContext', () => {
-    let mockIntegrationRepo;
-    let mockUserRepo;
-    let mockModuleRepo;
-    let mockCredentialRepo;
     let mockQueuerUtil;
 
     beforeEach(() => {
         jest.clearAllMocks();
 
-        mockIntegrationRepo = {
-            findIntegrations: jest.fn(),
-            findIntegrationById: jest.fn(),
-            findIntegrationsByUserId: jest.fn(),
-            updateIntegrationConfig: jest.fn(),
-            updateIntegrationStatus: jest.fn(),
-        };
-
-        mockUserRepo = {
-            findIndividualUserById: jest.fn(),
-            findIndividualUserByAppUserId: jest.fn(),
-            findIndividualUserByUsername: jest.fn(),
-        };
-
-        mockModuleRepo = {
-            findEntity: jest.fn(),
-            findEntityById: jest.fn(),
-            findEntitiesByUserId: jest.fn(),
-        };
-
-        mockCredentialRepo = {
-            findCredential: jest.fn(),
-            updateCredential: jest.fn(),
-        };
-
         mockQueuerUtil = {
             send: jest.fn().mockResolvedValue(undefined),
             batchSend: jest.fn().mockResolvedValue(undefined),
         };
 
-        const {
-            createIntegrationRepository,
-        } = require('@friggframework/core/integrations/repositories/integration-repository-factory');
-        const {
-            createUserRepository,
-        } = require('@friggframework/core/user/repositories/user-repository-factory');
-        const {
-            createModuleRepository,
-        } = require('@friggframework/core/modules/repositories/module-repository-factory');
-        const {
-            createCredentialRepository,
-        } = require('@friggframework/core/credential/repositories/credential-repository-factory');
         const { QueuerUtil } = require('@friggframework/core/queues');
-
-        createIntegrationRepository.mockReturnValue(mockIntegrationRepo);
-        createUserRepository.mockReturnValue(mockUserRepo);
-        createModuleRepository.mockReturnValue(mockModuleRepo);
-        createCredentialRepository.mockReturnValue(mockCredentialRepo);
-
         QueuerUtil.send = mockQueuerUtil.send;
         QueuerUtil.batchSend = mockQueuerUtil.batchSend;
     });
@@ -86,6 +30,19 @@ describe('AdminScriptContext', () => {
             expect(ctx.executionId).toBe('exec_123');
             expect(ctx.logs).toEqual([]);
             expect(ctx.integrationFactory).toBeNull();
+            expect(ctx.commands).toBeNull();
+        });
+
+        it('exposes the injected command bundle as context.commands', () => {
+            const commands = {
+                users: {},
+                credentials: {},
+                entities: {},
+                integrations: {},
+            };
+            const ctx = new AdminScriptContext({ commands });
+
+            expect(ctx.commands).toBe(commands);
         });
 
         it('creates with integrationFactory', () => {
@@ -106,71 +63,23 @@ describe('AdminScriptContext', () => {
         });
     });
 
-    describe('Lazy Repository Loading', () => {
-        it('creates integrationRepository on first access', () => {
+    describe('command surface (no direct repository access)', () => {
+        it('does not expose repository getters', () => {
             const ctx = new AdminScriptContext();
-            const {
-                createIntegrationRepository,
-            } = require('@friggframework/core/integrations/repositories/integration-repository-factory');
-
-            expect(createIntegrationRepository).not.toHaveBeenCalled();
 
-            const repo = ctx.integrationRepository;
-
-            expect(createIntegrationRepository).toHaveBeenCalledTimes(1);
-            expect(repo).toBe(mockIntegrationRepo);
+            expect(ctx.integrationRepository).toBeUndefined();
+            expect(ctx.userRepository).toBeUndefined();
+            expect(ctx.moduleRepository).toBeUndefined();
+            expect(ctx.credentialRepository).toBeUndefined();
         });
 
-        it('returns same instance on subsequent access', () => {
-            const ctx = new AdminScriptContext();
-
-            const repo1 = ctx.integrationRepository;
-            const repo2 = ctx.integrationRepository;
-
-            expect(repo1).toBe(repo2);
-            expect(repo1).toBe(mockIntegrationRepo);
-        });
-
-        it('creates userRepository on first access', () => {
-            const ctx = new AdminScriptContext();
-            const {
-                createUserRepository,
-            } = require('@friggframework/core/user/repositories/user-repository-factory');
-
-            expect(createUserRepository).not.toHaveBeenCalled();
-
-            const repo = ctx.userRepository;
-
-            expect(createUserRepository).toHaveBeenCalledTimes(1);
-            expect(repo).toBe(mockUserRepo);
-        });
-
-        it('creates moduleRepository on first access', () => {
-            const ctx = new AdminScriptContext();
-            const {
-                createModuleRepository,
-            } = require('@friggframework/core/modules/repositories/module-repository-factory');
-
-            expect(createModuleRepository).not.toHaveBeenCalled();
-
-            const repo = ctx.moduleRepository;
-
-            expect(createModuleRepository).toHaveBeenCalledTimes(1);
-            expect(repo).toBe(mockModuleRepo);
-        });
-
-        it('creates credentialRepository on first access', () => {
-            const ctx = new AdminScriptContext();
-            const {
-                createCredentialRepository,
-            } = require('@friggframework/core/credential/repositories/credential-repository-factory');
-
-            expect(createCredentialRepository).not.toHaveBeenCalled();
-
-            const repo = ctx.credentialRepository;
+        it('the context module never imports a repository factory', () => {
+            const source = fs.readFileSync(
+                path.join(__dirname, '..', 'admin-script-context.js'),
+                'utf8'
+            );
 
-            expect(createCredentialRepository).toHaveBeenCalledTimes(1);
-            expect(repo).toBe(mockCredentialRepo);
+            expect(source).not.toMatch(/repository-factory/);
         });
     });
 

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

@@ -38,9 +38,9 @@ describe('ScriptRunner', () => {
         scriptFactory = new ScriptFactory([TestScript]);
 
         mockCommands = {
-            createAdminProcess: jest.fn(),
-            updateAdminProcessState: jest.fn(),
-            completeAdminProcess: jest.fn(),
+            createExecution: jest.fn(),
+            updateExecutionState: jest.fn(),
+            completeExecution: jest.fn(),
         };
 
         mockContext = {
@@ -52,11 +52,11 @@ describe('ScriptRunner', () => {
         createAdminScriptCommands.mockReturnValue(mockCommands);
         createAdminScriptContext.mockReturnValue(mockContext);
 
-        mockCommands.createAdminProcess.mockResolvedValue({
+        mockCommands.createExecution.mockResolvedValue({
             id: 'exec-123',
         });
-        mockCommands.updateAdminProcessState.mockResolvedValue({});
-        mockCommands.completeAdminProcess.mockResolvedValue({ success: true });
+        mockCommands.updateExecutionState.mockResolvedValue({});
+        mockCommands.completeExecution.mockResolvedValue({ success: true });
     });
 
     afterEach(() => {
@@ -89,7 +89,7 @@ describe('ScriptRunner', () => {
             expect(result.executionId).toBe('exec-123');
             expect(result.metrics.durationMs).toBeGreaterThanOrEqual(0);
 
-            expect(mockCommands.createAdminProcess).toHaveBeenCalledWith({
+            expect(mockCommands.createExecution).toHaveBeenCalledWith({
                 scriptName: 'test-script',
                 scriptVersion: '1.0.0',
                 trigger: 'MANUAL',
@@ -98,12 +98,12 @@ describe('ScriptRunner', () => {
                 audit: { apiKeyName: 'test-key' },
             });
 
-            expect(mockCommands.updateAdminProcessState).toHaveBeenCalledWith(
+            expect(mockCommands.updateExecutionState).toHaveBeenCalledWith(
                 'exec-123',
                 'RUNNING'
             );
 
-            expect(mockCommands.completeAdminProcess).toHaveBeenCalledWith(
+            expect(mockCommands.completeExecution).toHaveBeenCalledWith(
                 'exec-123',
                 expect.objectContaining({
                     state: 'COMPLETED',
@@ -170,7 +170,7 @@ describe('ScriptRunner', () => {
             expect(result.scriptName).toBe('failing-script');
             expect(result.error.message).toBe('Script failed');
 
-            expect(mockCommands.completeAdminProcess).toHaveBeenCalledWith(
+            expect(mockCommands.completeExecution).toHaveBeenCalledWith(
                 'exec-123',
                 expect.objectContaining({
                     state: 'FAILED',
@@ -227,8 +227,8 @@ describe('ScriptRunner', () => {
             );
 
             expect(result.executionId).toBe('existing-exec-456');
-            expect(mockCommands.createAdminProcess).not.toHaveBeenCalled();
-            expect(mockCommands.updateAdminProcessState).toHaveBeenCalledWith(
+            expect(mockCommands.createExecution).not.toHaveBeenCalled();
+            expect(mockCommands.updateExecutionState).toHaveBeenCalledWith(
                 'existing-exec-456',
                 'RUNNING'
             );
@@ -237,7 +237,7 @@ describe('ScriptRunner', () => {
         it('reports COMPLETED even when persisting completion fails', async () => {
             // Commands return an error object (never throw). A successful script
             // must not be misreported as FAILED if the completion write fails.
-            mockCommands.completeAdminProcess.mockResolvedValue({
+            mockCommands.completeExecution.mockResolvedValue({
                 error: 500,
                 reason: 'DB write failed',
             });
@@ -257,7 +257,7 @@ describe('ScriptRunner', () => {
         });
 
         it('throws when the execution record cannot be created', async () => {
-            mockCommands.createAdminProcess.mockResolvedValue({
+            mockCommands.createExecution.mockResolvedValue({
                 error: 500,
                 reason: 'DB down',
             });
@@ -282,7 +282,7 @@ describe('ScriptRunner', () => {
 
             await runner.execute('test-script', {}, { trigger: 'MANUAL' });
 
-            expect(mockCommands.completeAdminProcess).toHaveBeenCalledWith(
+            expect(mockCommands.completeExecution).toHaveBeenCalledWith(
                 'exec-123',
                 expect.objectContaining({
                     logs: [{ level: 'info', message: 'hi' }],

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

@@ -3,23 +3,27 @@ const { QueuerUtil } = require('@friggframework/core/queues');
 /**
  * AdminScriptContext - Execution environment for admin scripts
  *
- * Provides a controlled surface area for scripts to interact with
- * the Frigg platform. Unique capabilities vs direct repo access:
+ * Provides a controlled surface area for scripts to interact with the Frigg
+ * platform. Scripts touch the database only through injected Frigg commands
+ * (`context.commands`) — never through repositories directly. Capabilities:
  *
+ * - **Frigg commands**: `commands.users`, `commands.credentials`,
+ *   `commands.entities`, and `commands.integrations` expose the framework's
+ *   command layer. Each command returns data on success or an `{ error }`
+ *   object on failure — scripts check `.error` themselves.
  * - **Admin bypass**: `instantiate()` passes `_isAdminContext: true` to
  *   skip user-ownership checks when loading integration instances
  * - **Script chaining**: `queueScript()` / `queueScriptBatch()` let scripts
  *   enqueue follow-up work with parent execution tracking
  * - **Execution-scoped logging**: `log()` collects structured entries tied
  *   to the current execution for post-run inspection
- * - **Lazy-loaded repositories**: Repos are exposed directly as getters
- *   so scripts can query any data they need without wrapper indirection
  */
 class AdminScriptContext {
     /**
      * @param {Object} [params={}] - Context configuration
-     * @param {string|number|null} [params.executionId] - ID of the AdminProcess record this context is scoped to (used for log persistence and script chaining)
+     * @param {string|number|null} [params.executionId] - ID of the AdminScriptExecution record this context is scoped to (used for log persistence and script chaining)
      * @param {Object|null} [params.integrationFactory] - Factory used to hydrate integration instances; required for scripts that call instantiate()
+     * @param {Object|null} [params.commands] - Frigg command bundle ({ users, credentials, entities, integrations }) injected by the composition root and exposed to scripts as context.commands
      */
     constructor(params = {}) {
         this.executionId = params.executionId || null;
@@ -27,54 +31,10 @@ class AdminScriptContext {
 
         this.integrationFactory = params.integrationFactory || null;
 
-        // Repositories are created on first use so the Prisma client is only
-        // initialized (and only for the repos a script actually touches) when needed.
-        this._integrationRepository = null;
-        this._userRepository = null;
-        this._moduleRepository = null;
-        this._credentialRepository = null;
-    }
-
-    // ==================== LAZY-LOADED REPOSITORIES ====================
-
-    get integrationRepository() {
-        if (!this._integrationRepository) {
-            const {
-                createIntegrationRepository,
-            } = require('@friggframework/core/integrations/repositories/integration-repository-factory');
-            this._integrationRepository = createIntegrationRepository();
-        }
-        return this._integrationRepository;
-    }
-
-    get userRepository() {
-        if (!this._userRepository) {
-            const {
-                createUserRepository,
-            } = require('@friggframework/core/user/repositories/user-repository-factory');
-            this._userRepository = createUserRepository();
-        }
-        return this._userRepository;
-    }
-
-    get moduleRepository() {
-        if (!this._moduleRepository) {
-            const {
-                createModuleRepository,
-            } = require('@friggframework/core/modules/repositories/module-repository-factory');
-            this._moduleRepository = createModuleRepository();
-        }
-        return this._moduleRepository;
-    }
-
-    get credentialRepository() {
-        if (!this._credentialRepository) {
-            const {
-                createCredentialRepository,
-            } = require('@friggframework/core/credential/repositories/credential-repository-factory');
-            this._credentialRepository = createCredentialRepository();
-        }
-        return this._credentialRepository;
+        // Scripts interact with the database only through these Frigg commands.
+        // Injected by bootstrap.js — the context never reaches for repositories
+        // or command factories itself.
+        this.commands = params.commands || null;
     }
 
     // ==================== INTEGRATION INSTANTIATION ====================

package/src/application/script-runner.js

@@ -17,10 +17,12 @@ class ScriptRunner {
      * @param {Object} params
      * @param {ScriptFactory} params.scriptFactory - Required. The registry used
      *   to resolve and instantiate scripts by name (built by bootstrap.js).
-     * @param {Object} [params.commands] - Admin process command layer; defaults
+     * @param {Object} [params.commands] - Admin script execution command layer; defaults
      *   to a fresh createAdminScriptCommands().
      * @param {Object} [params.integrationFactory] - Hydrates integration
      *   instances for scripts that need them.
+     * @param {Object} [params.scriptCommands] - Frigg command bundle exposed to
+     *   scripts as context.commands (built by bootstrap.js).
      */
     constructor(params = {}) {
         if (!params.scriptFactory) {
@@ -29,6 +31,7 @@ class ScriptRunner {
         this.scriptFactory = params.scriptFactory;
         this.commands = params.commands || createAdminScriptCommands();
         this.integrationFactory = params.integrationFactory || null;
+        this.scriptCommands = params.scriptCommands || null;
     }
 
     /**
@@ -39,8 +42,8 @@ class ScriptRunner {
      * @param {string} options.trigger - 'MANUAL' | 'SCHEDULED' | 'QUEUE'
      * @param {string} options.mode - 'sync' | 'async'
      * @param {Object} options.audit - Audit info { apiKeyName, apiKeyLast4, ipAddress }
-     * @param {string} options.executionId - Reuse existing AdminProcess record ID (NOT the Lambda execution ID).
-     *   This is the database ID from the AdminProcess collection/table that tracks script executions.
+     * @param {string} options.executionId - Reuse existing AdminScriptExecution record ID (NOT the Lambda execution ID).
+     *   This is the database ID from the AdminScriptExecution collection/table that tracks script executions.
      *   Pass this when resuming a queued execution to continue using the same execution record.
      */
     async execute(scriptName, params = {}, options = {}) {
@@ -75,7 +78,7 @@ class ScriptRunner {
 
         // Create execution record if not provided
         if (!executionId) {
-            const execution = await this.commands.createAdminProcess({
+            const execution = await this.commands.createExecution({
                 scriptName,
                 scriptVersion: definition.version,
                 trigger,
@@ -88,7 +91,8 @@ class ScriptRunner {
             // than tracking an `undefined` execution id.
             if (execution.error) {
                 throw new Error(
-                    execution.reason || 'Failed to create admin process record'
+                    execution.reason ||
+                        'Failed to create admin script execution record'
                 );
             }
             executionId = execution.id;
@@ -100,11 +104,12 @@ class ScriptRunner {
         const context = createAdminScriptContext({
             executionId,
             integrationFactory: this.integrationFactory,
+            commands: this.scriptCommands,
         });
 
         let output;
         try {
-            await this.commands.updateAdminProcessState(executionId, 'RUNNING');
+            await this.commands.updateExecutionState(executionId, 'RUNNING');
 
             // Create script instance with context injected via constructor
             const script = this.scriptFactory.createInstance(scriptName, {
@@ -118,7 +123,7 @@ class ScriptRunner {
         } catch (error) {
             const durationMs = new Date() - startTime;
 
-            const completion = await this.commands.completeAdminProcess(
+            const completion = await this.commands.completeExecution(
                 executionId,
                 {
                     state: 'FAILED',
@@ -165,7 +170,7 @@ class ScriptRunner {
             metrics: { durationMs },
         };
 
-        const completion = await this.commands.completeAdminProcess(
+        const completion = await this.commands.completeExecution(
             executionId,
             {
                 state: 'COMPLETED',

package/src/infrastructure/__tests__/admin-script-router.test.js

@@ -58,9 +58,9 @@ describe('Admin Script Router', () => {
         };
 
         mockCommands = {
-            createAdminProcess: jest.fn(),
-            findAdminProcessById: jest.fn(),
-            findAdminProcessesByName: jest.fn(),
+            createExecution: jest.fn(),
+            findExecutionById: jest.fn(),
+            findExecutionsByName: jest.fn(),
         };
 
         mockSchedulerAdapter = {
@@ -72,6 +72,7 @@ describe('Admin Script Router', () => {
         bootstrapAdminScripts.mockReturnValue({
             scriptFactory: mockFactory,
             integrationFactory: {},
+            scriptCommands: {},
         });
         createScriptRunner.mockReturnValue(mockRunner);
         createAdminScriptCommands.mockReturnValue(mockCommands);
@@ -177,13 +178,14 @@ describe('Admin Script Router', () => {
             expect(createScriptRunner).toHaveBeenCalledWith({
                 scriptFactory: mockFactory,
                 integrationFactory: {},
+                scriptCommands: {},
             });
         });
 
         it('should queue script for async execution', async () => {
             process.env.ADMIN_SCRIPT_QUEUE_URL =
                 'https://sqs.us-east-1.amazonaws.com/123/test-queue';
-            mockCommands.createAdminProcess.mockResolvedValue({
+            mockCommands.createExecution.mockResolvedValue({
                 id: 'exec-456',
             });
 
@@ -210,7 +212,7 @@ describe('Admin Script Router', () => {
         it('should default to async mode', async () => {
             process.env.ADMIN_SCRIPT_QUEUE_URL =
                 'https://sqs.us-east-1.amazonaws.com/123/test-queue';
-            mockCommands.createAdminProcess.mockResolvedValue({
+            mockCommands.createExecution.mockResolvedValue({
                 id: 'exec-789',
             });
 
@@ -255,7 +257,7 @@ describe('Admin Script Router', () => {
 
     describe('GET /admin/scripts/:scriptName/executions/:executionId', () => {
         it('should return execution details', async () => {
-            mockCommands.findAdminProcessById.mockResolvedValue({
+            mockCommands.findExecutionById.mockResolvedValue({
                 id: 'exec-123',
                 scriptName: 'test-script',
                 status: 'COMPLETED',
@@ -271,7 +273,7 @@ describe('Admin Script Router', () => {
         });
 
         it('should return 404 for non-existent execution', async () => {
-            mockCommands.findAdminProcessById.mockResolvedValue({
+            mockCommands.findExecutionById.mockResolvedValue({
                 error: 404,
                 reason: 'Execution not found',
                 code: 'EXECUTION_NOT_FOUND',
@@ -288,7 +290,7 @@ describe('Admin Script Router', () => {
 
     describe('GET /admin/scripts/:scriptName/executions', () => {
         it('should list executions for specific script', async () => {
-            mockCommands.findAdminProcessesByName.mockResolvedValue([
+            mockCommands.findExecutionsByName.mockResolvedValue([
                 { id: 'exec-1', name: 'test-script', state: 'COMPLETED' },
                 { id: 'exec-2', name: 'test-script', state: 'RUNNING' },
             ]);
@@ -299,7 +301,7 @@ describe('Admin Script Router', () => {
 
             expect(response.status).toBe(200);
             expect(response.body.executions).toHaveLength(2);
-            expect(mockCommands.findAdminProcessesByName).toHaveBeenCalledWith(
+            expect(mockCommands.findExecutionsByName).toHaveBeenCalledWith(
                 'test-script',
                 {
                     limit: 50,
@@ -308,13 +310,13 @@ describe('Admin Script Router', () => {
         });
 
         it('should accept query parameters (status maps to state, limit is bounded)', async () => {
-            mockCommands.findAdminProcessesByName.mockResolvedValue([]);
+            mockCommands.findExecutionsByName.mockResolvedValue([]);
 
             await request(app).get(
                 '/admin/scripts/test-script/executions?status=COMPLETED&limit=10'
             );
 
-            expect(mockCommands.findAdminProcessesByName).toHaveBeenCalledWith(
+            expect(mockCommands.findExecutionsByName).toHaveBeenCalledWith(
                 'test-script',
                 {
                     limit: 10,

package/src/infrastructure/__tests__/bootstrap.test.js

@@ -3,6 +3,27 @@ const { AdminScriptBase } = require('../../application/admin-script-base');
 
 jest.mock('@friggframework/core/handlers/app-definition-loader');
 
+// The command bundle is built from these factories; mock them so bootstrap
+// doesn't need a configured database to construct the command groups.
+jest.mock('@friggframework/core/application/commands/user-commands', () => ({
+    createUserCommands: jest.fn(() => ({ __kind: 'users' })),
+}));
+jest.mock(
+    '@friggframework/core/application/commands/credential-commands',
+    () => ({
+        createCredentialCommands: jest.fn(() => ({ __kind: 'credentials' })),
+    })
+);
+jest.mock('@friggframework/core/application/commands/entity-commands', () => ({
+    createEntityCommands: jest.fn(() => ({ __kind: 'entities' })),
+}));
+jest.mock(
+    '@friggframework/core/application/commands/integration-commands',
+    () => ({
+        createIntegrationCommands: jest.fn(() => ({ __kind: 'integrations' })),
+    })
+);
+
 const {
     loadAppDefinition,
 } = require('@friggframework/core/handlers/app-definition-loader');
@@ -64,9 +85,23 @@ describe('bootstrapAdminScripts', () => {
 
         expect(second.scriptFactory).toBe(first.scriptFactory);
         expect(second.integrationFactory).toBe(first.integrationFactory);
+        expect(second.scriptCommands).toBe(first.scriptCommands);
         expect(loadAppDefinition).toHaveBeenCalledTimes(1);
     });
 
+    it('builds the injectable command bundle (users, credentials, entities, integrations)', () => {
+        loadAppDefinition.mockReturnValue({ adminScripts: [] });
+
+        const { scriptCommands } = bootstrapAdminScripts();
+
+        expect(scriptCommands).toEqual({
+            users: { __kind: 'users' },
+            credentials: { __kind: 'credentials' },
+            entities: { __kind: 'entities' },
+            integrations: { __kind: 'integrations' },
+        });
+    });
+
     it('tolerates an app definition with no adminScripts', () => {
         loadAppDefinition.mockReturnValue({});
 

package/src/infrastructure/__tests__/script-executor-handler.test.js

@@ -12,20 +12,23 @@ const { handler } = require('../script-executor-handler');
 describe('Admin Script Executor Handler', () => {
     let mockScriptFactory;
     let mockIntegrationFactory;
+    let mockScriptCommands;
     let mockRunner;
     let mockCommands;
 
     beforeEach(() => {
         mockScriptFactory = { id: 'script-factory' };
         mockIntegrationFactory = { id: 'integration-factory' };
+        mockScriptCommands = { id: 'script-commands' };
         mockRunner = { execute: jest.fn() };
         mockCommands = {
-            completeAdminProcess: jest.fn().mockResolvedValue({}),
+            completeExecution: jest.fn().mockResolvedValue({}),
         };
 
         bootstrapAdminScripts.mockReturnValue({
             scriptFactory: mockScriptFactory,
             integrationFactory: mockIntegrationFactory,
+            scriptCommands: mockScriptCommands,
         });
         createScriptRunner.mockReturnValue(mockRunner);
         createAdminScriptCommands.mockReturnValue(mockCommands);
@@ -56,6 +59,7 @@ describe('Admin Script Executor Handler', () => {
             expect(createScriptRunner).toHaveBeenCalledWith({
                 scriptFactory: mockScriptFactory,
                 integrationFactory: mockIntegrationFactory,
+                scriptCommands: mockScriptCommands,
             });
             expect(mockRunner.execute).toHaveBeenCalledWith(
                 'my-script',
@@ -85,7 +89,7 @@ describe('Admin Script Executor Handler', () => {
             expect(response.statusCode).toBe(200);
             const body = JSON.parse(response.body);
             expect(body.results[0].status).toBe('FAILED');
-            expect(mockCommands.completeAdminProcess).toHaveBeenCalledWith(
+            expect(mockCommands.completeExecution).toHaveBeenCalledWith(
                 'exec-2',
                 expect.objectContaining({ state: 'FAILED' })
             );
@@ -114,6 +118,7 @@ describe('Admin Script Executor Handler', () => {
             expect(createScriptRunner).toHaveBeenCalledWith({
                 scriptFactory: mockScriptFactory,
                 integrationFactory: mockIntegrationFactory,
+                scriptCommands: mockScriptCommands,
             });
             expect(mockRunner.execute).toHaveBeenCalledWith(
                 'my-script',
@@ -154,7 +159,7 @@ describe('Admin Script Executor Handler', () => {
             expect(body.processed).toBe(2);
             expect(body.results[0].status).toBe('FAILED');
             expect(body.results[1].status).toBe('COMPLETED');
-            expect(mockCommands.completeAdminProcess).toHaveBeenCalledWith(
+            expect(mockCommands.completeExecution).toHaveBeenCalledWith(
                 'exec-bad',
                 expect.objectContaining({ state: 'FAILED' })
             );

package/src/infrastructure/admin-script-router.js

@@ -23,19 +23,12 @@ const {
 
 const router = express.Router();
 
-// Apply auth middleware to all admin routes
+// Apply auth middleware to all admin routes. Each handler then calls
+// bootstrapAdminScripts() (memoized, so it runs once per process) to obtain the
+// scriptFactory / integrationFactory / scriptCommands it needs — no global, and
+// endpoints that don't touch scripts skip the work entirely.
 router.use(validateAdminApiKey);
 
-// Build (once, memoized) and inject the per-process dependencies onto the
-// request, so route handlers consume them explicitly instead of reaching for a
-// global. Registers the host app's admin scripts on the first request.
-router.use((req, _res, next) => {
-    const { scriptFactory, integrationFactory } = bootstrapAdminScripts();
-    req.scriptFactory = scriptFactory;
-    req.integrationFactory = integrationFactory;
-    next();
-});
-
 /**
  * Translate a thrown error into an HTTP response. Boom errors (thrown by the
  * schedule use cases) carry their own status code; anything else is an
@@ -116,9 +109,9 @@ function createScheduleUseCases(scriptFactory) {
  * GET /admin/scripts
  * List all registered scripts
  */
-router.get('/scripts', async (req, res) => {
+router.get('/scripts', async (_req, res) => {
     try {
-        const factory = req.scriptFactory;
+        const { scriptFactory: factory } = bootstrapAdminScripts();
         const scripts = factory.getAll();
 
         res.json({
@@ -144,7 +137,7 @@ router.get('/scripts', async (req, res) => {
 router.get('/scripts/:scriptName', async (req, res) => {
     try {
         const { scriptName } = req.params;
-        const factory = req.scriptFactory;
+        const { scriptFactory: factory } = bootstrapAdminScripts();
 
         if (!factory.has(scriptName)) {
             return res.status(404).json({
@@ -179,7 +172,7 @@ router.post('/scripts/:scriptName/validate', async (req, res) => {
     try {
         const { scriptName } = req.params;
         const { params = {} } = req.body;
-        const factory = req.scriptFactory;
+        const { scriptFactory: factory } = bootstrapAdminScripts();
 
         if (!factory.has(scriptName)) {
             return res.status(404).json({
@@ -204,7 +197,11 @@ router.post('/scripts/:scriptName', async (req, res) => {
     try {
         const { scriptName } = req.params;
         const { params = {}, mode = 'async' } = req.body;
-        const factory = req.scriptFactory;
+        const {
+            scriptFactory: factory,
+            integrationFactory,
+            scriptCommands,
+        } = bootstrapAdminScripts();
 
         if (!factory.has(scriptName)) {
             return res.status(404).json({
@@ -242,8 +239,9 @@ router.post('/scripts/:scriptName', async (req, res) => {
             }
 
             const runner = createScriptRunner({
-                scriptFactory: req.scriptFactory,
-                integrationFactory: req.integrationFactory,
+                scriptFactory: factory,
+                integrationFactory,
+                scriptCommands,
             });
             const result = await runner.execute(scriptName, params, {
                 trigger: 'MANUAL',
@@ -263,7 +261,7 @@ router.post('/scripts/:scriptName', async (req, res) => {
         }
 
         const commands = createAdminScriptCommands();
-        const execution = await commands.createAdminProcess({
+        const execution = await commands.createExecution({
             scriptName,
             scriptVersion: definition.version,
             trigger: 'MANUAL',
@@ -311,7 +309,7 @@ router.get('/scripts/:scriptName/executions/:executionId', async (req, res) => {
     try {
         const { executionId } = req.params;
         const commands = createAdminScriptCommands();
-        const execution = await commands.findAdminProcessById(executionId);
+        const execution = await commands.findExecutionById(executionId);
 
         if (execution.error) {
             return res.status(execution.error).json({
@@ -342,7 +340,7 @@ router.get('/scripts/:scriptName/executions', async (req, res) => {
             ? 50
             : Math.min(Math.max(parsedLimit, 1), 200);
 
-        const executions = await commands.findAdminProcessesByName(scriptName, {
+        const executions = await commands.findExecutionsByName(scriptName, {
             limit: safeLimit,
             ...(status && { state: status }),
         });
@@ -361,9 +359,8 @@ router.get('/scripts/:scriptName/executions', async (req, res) => {
 router.get('/scripts/:scriptName/schedule', async (req, res) => {
     try {
         const { scriptName } = req.params;
-        const { getEffectiveSchedule } = createScheduleUseCases(
-            req.scriptFactory
-        );
+        const { scriptFactory } = bootstrapAdminScripts();
+        const { getEffectiveSchedule } = createScheduleUseCases(scriptFactory);
 
         const result = await getEffectiveSchedule.execute(scriptName);
 
@@ -385,7 +382,8 @@ router.put('/scripts/:scriptName/schedule', async (req, res) => {
     try {
         const { scriptName } = req.params;
         const { enabled, cronExpression, timezone } = req.body;
-        const { upsertSchedule } = createScheduleUseCases(req.scriptFactory);
+        const { scriptFactory } = bootstrapAdminScripts();
+        const { upsertSchedule } = createScheduleUseCases(scriptFactory);
 
         const result = await upsertSchedule.execute(scriptName, {
             enabled,
@@ -415,7 +413,8 @@ router.put('/scripts/:scriptName/schedule', async (req, res) => {
 router.delete('/scripts/:scriptName/schedule', async (req, res) => {
     try {
         const { scriptName } = req.params;
-        const { deleteSchedule } = createScheduleUseCases(req.scriptFactory);
+        const { scriptFactory } = bootstrapAdminScripts();
+        const { deleteSchedule } = createScheduleUseCases(scriptFactory);
 
         const result = await deleteSchedule.execute(scriptName);
 

package/src/infrastructure/bootstrap.js

@@ -15,6 +15,7 @@ const { ScriptFactory } = require('../application/script-factory');
  */
 let bootstrapped = false;
 let scriptFactory = null;
+let scriptCommands = null;
 let integrationFactory = null;
 
 function registerScripts(factory, scriptClasses) {
@@ -45,11 +46,41 @@ function createIntegrationFactory() {
 }
 
 /**
- * @returns {{ scriptFactory: ScriptFactory, integrationFactory: object }}
+ * Build the command bundle injected into every AdminScriptContext. Scripts
+ * interact with the database only through these Frigg commands — never through
+ * repositories directly. The require is lazy so the package keeps no load-time
+ * coupling to core's command/repository modules.
+ */
+function buildScriptCommands() {
+    const {
+        createUserCommands,
+    } = require('@friggframework/core/application/commands/user-commands');
+    const {
+        createCredentialCommands,
+    } = require('@friggframework/core/application/commands/credential-commands');
+    const {
+        createEntityCommands,
+    } = require('@friggframework/core/application/commands/entity-commands');
+    const {
+        createIntegrationCommands,
+    } = require('@friggframework/core/application/commands/integration-commands');
+
+    return {
+        users: createUserCommands(),
+        credentials: createCredentialCommands(),
+        entities: createEntityCommands(),
+        // Class-agnostic reads (findIntegrationById, listIntegrations). Scripts
+        // that need class-scoped integration ops build their own commands.
+        integrations: createIntegrationCommands(),
+    };
+}
+
+/**
+ * @returns {{ scriptFactory: ScriptFactory, scriptCommands: object, integrationFactory: object }}
  */
 function bootstrapAdminScripts() {
     if (bootstrapped) {
-        return { scriptFactory, integrationFactory };
+        return { scriptFactory, scriptCommands, integrationFactory };
     }
     bootstrapped = true;
 
@@ -72,14 +103,26 @@ function bootstrapAdminScripts() {
         );
     }
 
+    // Built in its own try so a command-layer failure never blocks script
+    // registration (and vice versa) — both honor the never-throw contract.
+    try {
+        scriptCommands = buildScriptCommands();
+    } catch (error) {
+        console.error(
+            '[admin-scripts] bootstrap: could not build command bundle:',
+            error.message
+        );
+    }
+
     integrationFactory = createIntegrationFactory();
-    return { scriptFactory, integrationFactory };
+    return { scriptFactory, scriptCommands, integrationFactory };
 }
 
 /** Test-only: reset memoized bootstrap state. */
 function _resetBootstrapForTests() {
     bootstrapped = false;
     scriptFactory = null;
+    scriptCommands = null;
     integrationFactory = null;
 }
 

package/src/infrastructure/script-executor-handler.js

@@ -8,7 +8,7 @@ const { bootstrapAdminScripts } = require('./bootstrap');
  * Run a single execution message through the ScriptRunner.
  * @param {Object} message - Parsed execution message.
  * @param {string} message.scriptName - Name of the registered script to run (required).
- * @param {string} [message.executionId] - Existing AdminProcess id to resume; when
+ * @param {string} [message.executionId] - Existing AdminScriptExecution id to resume; when
  *   absent, ScriptRunner creates a new record.
  * @param {string} [message.trigger] - Execution trigger; defaults to 'QUEUE'.
  * @param {Object} [message.params] - Parameters passed to the script.
@@ -16,10 +16,14 @@ const { bootstrapAdminScripts } = require('./bootstrap');
  * @param {Object} deps
  * @param {ScriptFactory} deps.scriptFactory - Registry used to resolve and instantiate the script.
  * @param {Object} deps.integrationFactory - Hydrates integration instances for scripts that need them.
+ * @param {Object} deps.scriptCommands - Frigg command bundle exposed to the script as context.commands.
  * @returns {Promise<{ scriptName: string, status: string, executionId: string }>}
  * @private
  */
-async function runMessage(message, { scriptFactory, integrationFactory }) {
+async function runMessage(
+    message,
+    { scriptFactory, integrationFactory, scriptCommands }
+) {
     const { scriptName, executionId, trigger, params, parentExecutionId } =
         message;
 
@@ -33,7 +37,11 @@ async function runMessage(message, { scriptFactory, integrationFactory }) {
         }`
     );
 
-    const runner = createScriptRunner({ scriptFactory, integrationFactory });
+    const runner = createScriptRunner({
+        scriptFactory,
+        integrationFactory,
+        scriptCommands,
+    });
     const result = await runner.execute(scriptName, params, {
         trigger: trigger || 'QUEUE',
         mode: 'async',
@@ -51,7 +59,7 @@ async function runMessage(message, { scriptFactory, integrationFactory }) {
 }
 
 /**
- * Mark an admin process FAILED when the worker itself blows up (parse error,
+ * Mark an admin script execution FAILED when the worker itself blows up (parse error,
  * runner construction), so the record doesn't stay stuck in a non-terminal
  * state. No-op when there is no execution id.
  * @private
@@ -60,7 +68,7 @@ async function markFailed(executionId, error) {
     if (!executionId) return;
     try {
         const commands = createAdminScriptCommands();
-        await commands.completeAdminProcess(executionId, {
+        await commands.completeExecution(executionId, {
             state: 'FAILED',
             error: {
                 name: error.name,
@@ -80,7 +88,7 @@ async function markFailed(executionId, error) {
  * Handle an EventBridge Scheduler direct invoke: the event itself is a single
  * execution message (no `Records` wrapper).
  * @param {Object} event - The execution message.
- * @param {{ scriptFactory: ScriptFactory, integrationFactory: object }} deps
+ * @param {{ scriptFactory: ScriptFactory, integrationFactory: object, scriptCommands: object }} deps
  * @returns {Promise<{ statusCode: number, body: string }>}
  * @private
  */
@@ -118,7 +126,7 @@ async function handleScheduledInvoke(event, deps) {
  * (manual async executions and queueScript continuations). Failures are isolated
  * per record so one bad message doesn't drop the rest of the batch.
  * @param {Object} event - The SQS event with a `Records` array.
- * @param {{ scriptFactory: ScriptFactory, integrationFactory: object }} deps
+ * @param {{ scriptFactory: ScriptFactory, integrationFactory: object, scriptCommands: object }} deps
  * @returns {Promise<{ statusCode: number, body: string }>}
  * @private
  */