at-mintel/.agent/workflows/cms-workflow.md

description

description
How to manage and deploy Directus CMS infrastructure changes.

Directus CMS Infrastructure Workflow

This workflow ensures "Industrial Grade" consistency and stability across local, testing, and production environments for the at-mintel Directus CMS.

1. Local Development Lifecycle

Starting the CMS

To start the local Directus instance with extensions:

cd packages/cms-infra
npm run up

Modifying Schema

1. Directus UI: Make your changes directly in the local Directus Admin UI (Collections, Fields, Relations).
2. Take Snapshot:

   cd packages/cms-infra
   npm run snapshot:local
   

   This updates packages/cms-infra/schema/snapshot.yaml.
3. Commit: Commit the updated snapshot.yaml.

2. Deploying Schema Changes

To Local Environment (Reconciliation)

If you pull changes from Git and need to apply them to your local database:

cd packages/cms-infra
npm run schema:apply:local

Important

This command automatically runs scripts/cms-reconcile.sh to prevent "Field already exists" errors by registering database columns in Directus metadata first.

To Production (Infra)

To deploy the local snapshot to the production server:

cd packages/cms-infra
npm run schema:apply:infra

This script:

1. Syncs built extensions via rsync.
2. Injects the snapshot.yaml into the remote container.
3. Runs directus schema apply.
4. Restarts Directus to clear the schema cache.

3. Data Synchronization

Pulling from Production

To update your local environment with production data and assets:

cd packages/cms-infra
npm run sync:pull

Pushing to Production

Caution

This will overwrite production data. Use with extreme care.

cd packages/cms-infra
npm run sync:push

4. Extension Management

When modifying extensions in packages/*-manager:

1. Extensions are automatically built and synced when running npm run up.
2. To sync manually without restarting the stack:

   cd packages/cms-infra
   npm run build:extensions
   

5. Troubleshooting "Field already exists"

If schema:apply fails with "Field already exists", run:

./scripts/cms-reconcile.sh

This script ensures the database state matches Directus's internal field registry (directus_fields).