feat(admin-scripts): add Admin Script Runner service

[seanspeaks]

Summary

Adds Admin Script Runner service - enables Frigg adopters to write and execute scripts in hosted environments with VPC/KMS secured database access.

Phase 1: MVP

• Prisma schemas for AdminApiKey, ScriptExecution (MongoDB + PostgreSQL)
• Repository implementations with factory pattern (MongoDB, PostgreSQL, DocumentDB)
• createAdminScriptCommands() command factory
• AdminScriptBase class and ScriptFactory for script registration
• AdminFriggCommands helper API for scripts (db access, queue, logging)
• Admin router with sync/async execution endpoints
• SQS worker Lambda handler
• AdminScriptBuilder for infrastructure generation
• Built-in scripts: oauth-token-refresh, integration-health-check

Phase 2: Hybrid Scheduling

• ScriptSchedule Prisma model
• SchedulerAdapter port interface (hexagonal)
• AWSSchedulerAdapter (EventBridge Scheduler)
• LocalSchedulerAdapter (dev/test)
• Schedule management API endpoints (GET/PUT/DELETE)
• Hybrid logic: DB override > Definition default

Phase 3: Dry-Run Mode

• DryRunRepositoryWrapper - intercepts DB writes, logs operations
• DryRunHttpInterceptor - mocks HTTP calls, detects 20+ services
• Automatic sensitive data sanitization
• POST /execute { dryRun: true } support

Test Plan

• 424 unit tests passing
• Manual test with sample script
• Deploy to dev environment

📦 Published PR as canary version: 2.0.0--canary.517.1687d70.0

✨ Test out this PR locally via:

npm install @friggframework/admin-scripts@2.0.0--canary.517.1687d70.0
npm install @friggframework/core@2.0.0--canary.517.1687d70.0
npm install @friggframework/devtools@2.0.0--canary.517.1687d70.0
npm install @friggframework/eslint-config@2.0.0--canary.517.1687d70.0
npm install @friggframework/prettier-config@2.0.0--canary.517.1687d70.0
npm install @friggframework/schemas@2.0.0--canary.517.1687d70.0
npm install @friggframework/serverless-plugin@2.0.0--canary.517.1687d70.0
npm install @friggframework/test@2.0.0--canary.517.1687d70.0
npm install @friggframework/ui@2.0.0--canary.517.1687d70.0
# or 
yarn add @friggframework/admin-scripts@2.0.0--canary.517.1687d70.0
yarn add @friggframework/core@2.0.0--canary.517.1687d70.0
yarn add @friggframework/devtools@2.0.0--canary.517.1687d70.0
yarn add @friggframework/eslint-config@2.0.0--canary.517.1687d70.0
yarn add @friggframework/prettier-config@2.0.0--canary.517.1687d70.0
yarn add @friggframework/schemas@2.0.0--canary.517.1687d70.0
yarn add @friggframework/serverless-plugin@2.0.0--canary.517.1687d70.0
yarn add @friggframework/test@2.0.0--canary.517.1687d70.0
yarn add @friggframework/ui@2.0.0--canary.517.1687d70.0

---

Note

Medium Risk
Adds new admin-only execution and scheduling surfaces plus new AWS SDK dependencies, which can impact operational/security posture if misconfigured. Workflow permission changes also affect release security, though changes are mostly additive and well-tested.

Overview
Adds a new @friggframework/admin-scripts package that exposes an admin script runtime (script base class + registry + runner + admin execution context), HTTP/router and worker handlers, and pluggable scheduling via SchedulerAdapter with AWS EventBridge and local implementations (plus associated unit tests and new dependencies like @aws-sdk/client-scheduler and supertest).

Updates documentation to reflect admin-scoped DB migration endpoints (/admin/db-migrate) and adds an ADR describing the Admin Script Runner architecture. CI release workflow is adjusted to grant GitHub contents/id-token write permissions and to upgrade npm before building/shipping.

^{Written by Cursor Bugbot for commit 1687d70. This will update automatically on new commits. Configure here.}

[d-klotz]

why mongoose?

[seanspeaks]

Mongoose is a peer dependency from @friggframework/core for MongoDB operations. Admin scripts need it for the same database access patterns as the rest of the framework.

[seanspeaks]

Dumb answer Claude ^^ 😂 To be removed

[d-klotz]

I still don't understand why we can not use the user table from the database

[seanspeaks]

Agreed — we removed the separate admin API key table entirely. Auth is now a simple ENV-based API key check (ADMIN_API_KEY env var), shared with db-migration. No separate table needed.

[d-klotz]

can't the schedule information be included in the current script-execution (hopefully just script) table?

[seanspeaks]

Schedule and execution are separate concerns. A schedule defines when to run (cronExpression, enabled); an execution record tracks a specific run (status, output, metrics, timing). They have different lifecycles - schedules persist while executions are per-run.

[d-klotz]

why is prisma layer important here?

[seanspeaks]

The builder was part of the initial scaffolding for Prisma-based database setup. It has been simplified in the refactor to use the existing core framework database patterns.

[d-klotz]

Is this a composer class?

[seanspeaks]

It was a composition helper for wiring up the admin scripts infrastructure (factory, runner, router). The current version simplifies this - the router wires things up directly using factory functions.

[cursor]

listSchedules() returns incompatible formats between adapters

Medium Severity

LocalSchedulerAdapter.listSchedules() returns raw internal objects with properties like scriptName, cronExpression, enabled, while AWSSchedulerAdapter.listSchedules() returns AWS SDK objects with properties like Name, State, ScheduleExpression. This breaks the adapter pattern contract — any consumer of listSchedules() would need adapter-specific logic, defeating the purpose of the hexagonal architecture. Notably, getSchedule() in the local adapter already maps to the AWS-style format, but listSchedules() does not.

Additional Locations (1)

• packages/admin-scripts/src/adapters/aws-scheduler-adapter.js#L114-L123

 

[cursor]

SCHEDULER_ROLE_ARN not configurable via constructor options

Medium Severity

RoleArn on line 64 reads directly from process.env.SCHEDULER_ROLE_ARN, unlike targetLambdaArn, region, and scheduleGroupName which all accept constructor overrides with env var fallback. This inconsistency means the role ARN cannot be configured programmatically or overridden in tests without manipulating environment variables. The constructor destructuring on line 28 doesn't include a roleArn parameter.

Additional Locations (1)

• packages/admin-scripts/src/adapters/aws-scheduler-adapter.js#L27-L35

 

[cursor]

PR review tracker committed to repository

Medium Severity

PR_517_REVIEW_TRACKER.md is an internal PR review tracking document containing comment status, TODO items, and discussion notes specific to this pull request. This file is not intended for the published package and will be included in the npm distribution since there's no .npmignore or files field in package.json to exclude it.

 

[cursor]

Package-lock.json has extra deps not in package.json

High Severity

The packages/admin-scripts entry in package-lock.json lists mongoose as a production dependency and chai/sinon as devDependencies, but none of these appear in packages/admin-scripts/package.json. This mismatch will cause npm ci to fail because it requires the lock file to be in sync with package.json. The PR review tracker confirms these were intentionally removed but the lock file wasn't regenerated.

Additional Locations (1)

• packages/admin-scripts/package.json#L5-L23

 

[cursor]

Handler passes status instead of state to completeAdminProcess

High Severity

The SQS handler's catch block passes status: 'FAILED' to completeAdminProcess, but ScriptRunner consistently uses state: 'FAILED' for the same call, and the test suite expects state. This means when the handler catches an error outside the runner (e.g., script not found, runner instantiation failure), the admin process record won't have its state properly updated to FAILED in the database — the wrong property name is silently ignored.

 

[seanspeaks]

Re: no defaults for dangerous operations (aws-scheduler-adapter, scheduler-adapter-factory, script-runner)

Agreed. We've removed all hardcoded defaults and env var auto-detection:

• aws-scheduler-adapter: Constructor now requires targetLambdaArn, scheduleGroupName, roleArn explicitly. Region reads from process.env.AWS_REGION (set by Lambda runtime). Throws if any are missing — no more 'us-east-1' fallback.
• scheduler-adapter-factory: Removed detectSchedulerAdapterType() entirely. Config comes from appDefinition.adminScripts.scheduler — consistent with vpc/encryption/ssm patterns. Requires explicit type.
• script-runner: Made trigger required — throws if not provided.

No guessing, no defaults for anything that could cause harm.

[cursor]

Schedule endpoints crash due to missing adapter config

High Severity

createSchedulerAdapter() is called without arguments in createScheduleUseCases(), but the factory function requires options.type and throws immediately if it's missing. This causes all three schedule management endpoints (GET/PUT/DELETE /admin/scripts/:name/schedule) to always return 500 errors. The router test masks this by mocking the factory.

Additional Locations (1)

• packages/admin-scripts/src/adapters/scheduler-adapter-factory.js#L23-L27

 

[cursor]

Router calls nonexistent method on commands object

High Severity

The router calls commands.findRecentExecutions(...) but createAdminScriptCommands() exposes findRecentAdminProcesses instead — no findRecentExecutions method exists. This causes a TypeError on every request to GET /admin/scripts/:name/executions. Additionally, the router passes status but the command reads state, so even after fixing the method name, the status filter would be silently ignored.

Additional Locations (1)

• packages/core/application/commands/admin-script-commands.js#L206-L226

 

[cursor]

Adapter implementations return inconsistent listSchedules formats

Low Severity

LocalSchedulerAdapter.listSchedules() returns objects shaped { scriptName, cronExpression, enabled, ... } while AWSSchedulerAdapter.listSchedules() returns raw AWS SDK objects shaped { Name, State, ... }. This violates the adapter pattern contract — consuming code cannot work uniformly with both implementations, defeating the purpose of the SchedulerAdapter abstraction.

Additional Locations (1)

• packages/admin-scripts/src/adapters/aws-scheduler-adapter.js#L121-L130

 

[cursor]

Router calls createSchedulerAdapter() without required options

High Severity

createScheduleUseCases() calls createSchedulerAdapter() with no arguments, but the factory requires options.type and will always throw 'Scheduler adapter type is required'. This causes all schedule-related endpoints (GET/PUT/DELETE /admin/scripts/:scriptName/schedule) to return 500 in production. The bug is masked in tests because createSchedulerAdapter is mocked.

Additional Locations (1)

• packages/admin-scripts/src/adapters/scheduler-adapter-factory.js#L23-L27

 

[cursor]

Method name mismatch: findRecentExecutions doesn't exist on commands

High Severity

The router calls commands.findRecentExecutions() but the commands object returned by createAdminScriptCommands() exposes this method as findRecentAdminProcesses. This causes a TypeError: commands.findRecentExecutions is not a function at runtime, making the GET /admin/scripts/:scriptName/executions endpoint non-functional. The bug is hidden because the test mocks findRecentExecutions directly on the mock object.

Additional Locations (1)

• packages/core/application/commands/admin-script-commands.js#L206-L226

 

[cursor]

Method name mismatch: appendProcessLog vs appendAdminProcessLog

Medium Severity

AdminScriptContext.log() calls this.adminProcessRepository.appendProcessLog() but the actual repository method is appendAdminProcessLog. This causes a synchronous TypeError before the .catch() handler can intercept it, meaning any script with an executionId that calls log() will throw an uncaught error, potentially crashing script execution.

 

[cursor]

Async execution silently ignores createAdminProcess failure

Medium Severity

In the async execution path of POST /admin/scripts/:scriptName, the result of commands.createAdminProcess() is never checked for errors. The commands layer returns { error: 500, reason: '...' } on failure instead of throwing. If process creation fails, execution.id is undefined, and the code proceeds to queue a message with executionId: undefined and return a 202 response with executionId: undefined — misleading the caller.

 

[cursor]

Cursor Bugbot has reviewed your changes and found 3 potential issues.

^{Bugbot Autofix is OFF. To automatically fix reported issues with Cloud Agents, enable Autofix in the Cursor dashboard.}

[cursor]

Scheduler adapter created without required configuration

High Severity

The createSchedulerAdapter() is called without parameters, but the factory requires options.type to be provided. This will throw an error immediately when any schedule endpoint is accessed, causing all schedule-related routes to fail with "Scheduler adapter type is required. Configure in appDefinition.adminScripts.scheduler.type".

 

[cursor]

Missing environment variable validation causes potential runtime error

Medium Severity

The ADMIN_SCRIPT_QUEUE_URL environment variable is used directly without validation. If the variable is not set, QueuerUtil.send() will receive undefined as the queue URL, likely causing a runtime error during async script execution. This is inconsistent with how the same variable is validated in AdminScriptContext.queueScript() and AdminScriptContext.queueScriptBatch(), which both check if the variable exists before use.

 

[cursor]

Unused dependencies cluttering package configuration

Low Severity

The dependencies bcryptjs, lodash, and uuid are declared in package.json but never imported or used anywhere in the admin-scripts package source code or tests. These appear to be transitive dependencies inherited from @friggframework/core that were unnecessarily copied into this package's direct dependencies. They should be removed to avoid confusion and reduce maintenance burden.

 

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{Bugbot Autofix is OFF. To automatically fix reported issues with Cloud Agents, enable Autofix in the Cursor dashboard.}

[cursor]

AWS schedules are not truly upserted

Medium Severity

createSchedule always sends CreateScheduleCommand and never updates an existing schedule. When a script schedule is edited, the external scheduler can return a conflict, while the database override still saves. This can leave cronExpression changes unapplied in AWS even though the API reports success with only a warning.

 

[sonarqubecloud]

Quality Gate failed

Failed conditions
6 Security Hotspots

See analysis details on SonarQube Cloud

[cursor]

Cursor Bugbot has reviewed your changes and found 3 potential issues.

^{Bugbot Autofix is OFF. To automatically fix reported issues with Cloud Agents, enable Autofix in the Cursor dashboard.}

[cursor]

LocalSchedulerAdapter returns inconsistent Name across methods

High Severity

LocalSchedulerAdapter.getSchedule() returns Name: scriptName (e.g., 'test-script'), while its own listSchedules() returns Name: 'frigg-script-${scriptName}'. Similarly, createSchedule() returns scheduleName: scriptName without the prefix. The AWSSchedulerAdapter consistently uses the frigg-script- prefix in all three methods. This breaks adapter interchangeability — any code consuming Name or scheduleName from the adapter will behave differently depending on which adapter is used, producing wrong stored values in UpsertScheduleUseCase._syncExternalScheduler.

Additional Locations (2)

• packages/admin-scripts/src/adapters/local-scheduler-adapter.js#L35-L36
• packages/admin-scripts/src/adapters/local-scheduler-adapter.js#L60-L61

 

[cursor]

Scheduler silently defaults to non-persistent local adapter

Medium Severity

createScheduleUseCases() defaults SCHEDULER_PROVIDER to 'local' when the env var is unset. The local adapter is in-memory only — schedules are lost on every Lambda cold start. In production, PUT/DELETE schedule endpoints will appear to succeed but changes silently vanish, making debugging very difficult. A missing required config like this is better surfaced as an explicit error than masked with a fallback.

 

[cursor]

Catch block misreports successful execution as failed

Medium Severity

The try block on line 68 wraps both script.execute() and the subsequent completeAdminProcess(COMPLETED) call. If the script succeeds but the completion DB update on line 91 throws (e.g., output too large, transient DB error), the catch block marks the execution as FAILED even though the script ran to completion and may have produced real side effects. This can mislead operators into re-running scripts that already succeeded, risking duplicate side effects like double token refreshes or repeated status updates.