create-job

name	create-job
description	Create job files in the Commons monorepo. Use when the user wants to create a new job, backfill script, cache job, export job, sync job, bulk operation, cron task, or any background task that runs via HTTP POST endpoint.

Create Job

Create background jobs that run as HTTP POST endpoints in the Commons worker.

How Jobs Work

• Files in commons-packages/backend/src/jobs/ are auto-discovered by filename
• Available as HTTP POST /jobs/<filename-without-extension>
• The handler in script-execute-handler.ts dynamically require()s the file and wraps it in BatchJobRun.trap() for lifecycle tracking
• Legacy paths /scripts/<slug> and /cron/<slug> also work but /jobs/ is preferred
• Cloud Scheduler cron jobs: filename must match the Cloud Scheduler job name

When to Use

• Backfilling data, caching external data, bulk operations, exports, syncs, workflow triggers, data cleanup, scheduled cron tasks

When NOT to Use

• Schema changes → use @database-migration
• One-off data queries → provide SQL to the user

File Location

commons-packages/backend/src/jobs/{kebab-case-name}.ts

Tests: commons-packages/backend/src/jobs/__tests__/{kebab-case-name}.spec.ts

Shared helpers: commons-packages/backend/src/jobs/shared/ or commons-packages/backend/src/jobs/helpers/

Job Categories and Naming