feat: migrations run cmd

[alvarosabu]

Migrations Run Command

The storyblok migrations run command allows you to execute content migrations on your Storyblok stories. This is particularly useful for batch updating content, transforming field values, or restructuring content across multiple stories in a space.

Prerequisites

Before running migrations, ensure you have:

1. The necessary migration files in your .storyblok/migrations/{spaceId} directory
2. Proper access to the target space
3. A backup of your content (recommended)

Basic Usage

# Run all migrations in a space
storyblok migrations run --space 12345

# Run migrations for a specific component
storyblok migrations run hero --space 12345

# Preview changes without applying them
storyblok migrations run --space 12345 --dry-run

Architecture & Flow

The migrations command is organized in three main layers with a specific processing flow to ensure safe and efficient content updates.

Command Structure

// 1. Command Layer (index.ts)
migrationsCommand
  .command('run [componentName]')
  // ... options

// 2. Operations Layer (operations.ts)
  - handleMigrations()
  - summarizeMigrationResults()

// 3. Actions Layer (actions.ts)
  - readMigrationFiles()
  - updateStory()
  - fetchStoriesByComponent();

Processing Flow Examples

1. Simple Migration Run

storyblok migrations run --space 12345

Flow:

1. Read Phase

// 1. Read migration files from .storyblok/migrations/12345/
const migrationFiles = await readMigrationFiles({
  space: '12345',
  path: undefined,
  filter: undefined
});

// 2. Fetch stories from space
const stories = await fetchStoriesByComponent({
  spaceId: '12345',
  token: 'valid-token',
  region: 'eu'
});

2. Migration Phase

// 3. Process migrations
const migrationResults = await handleMigrations({
  migrationFiles,
  stories,
  space: '12345',
  // ... other options
});

3. Update Phase

// 4. Update modified stories
for (const story of storiesToUpdate) {
  await updateStory('12345', token, region, story.id, {
    story: {
      content: story.content,
      // ... other fields
    },
    force_update: '1'
  });
}

2. Component-Specific Migration

storyblok migrations run hero --space 12345

Flow:

1. Filter Phase

// 1. Filter migrations by component name
const filteredMigrations = migrationFiles.filter((file) => {
  return file.name.match(new RegExp(`^${componentName}(\\..*)?\.js$`));
});

// 2. Fetch stories with component
const stories = await fetchStoriesByComponent({
  spaceId: '12345',
  componentName: 'hero'
});

2. Process & Update

// 3. Apply migrations only to matching stories
const results = await handleMigrations({
  migrationFiles: filteredMigrations,
  stories,
  // ... other options
});

3. Publication Control

storyblok migrations run --space 12345 --publish published

Flow:

1. Story Update

// 1. Prepare update payload with publish flag
const payload = {
  story: {
    content: story.content,
    id: story.id,
    name: story.name
  },
  force_update: '1'
};

// 2. Add publish flag based on conditions
if (publish === 'published' && story.published) {
  payload.publish = 1;
}

// 3. Update story with publish control
await updateStory('12345', token, region, story.id, payload);

4. Story Filtering by Path

storyblok migrations run --space 12345 --starts-with "/en/blog/"

Flow:

1. Story Fetching with Path Filter

// 1. Fetch stories with path filter
const stories = await fetchStoriesByComponent({
  spaceId: '12345',
  token: 'valid-token',
  region: 'eu',
  starts_with: '/en/blog/'
});

// 2. Process only stories that match the path
const migrationResults = await handleMigrations({
  migrationFiles,
  stories, // Only contains stories under /en/blog/
  space: '12345',
  // ... other options
});

5. Story Filtering by Query

storyblok migrations run --space 12345 --query "[highlighted][in]=true"

Flow:

1. Story Fetching with Query Filter

// 1. Fetch stories with query filter
const stories = await fetchStoriesByComponent({
  spaceId: '12345',
  token: 'valid-token',
  region: 'eu',
  query: '[highlighted][in]=true'
});

// 2. Process only stories that match the query
const migrationResults = await handleMigrations({
  migrationFiles,
  stories, // Only contains stories where highlighted=true
  space: '12345',
  // ... other options
});

// 3. Example with multiple query conditions
const storiesWithMultipleConditions = await fetchStoriesByComponent({
  spaceId: '12345',
  token: 'valid-token',
  region: 'eu',
  query: '[highlighted][in]=true,[status][in]=published'
});

Key Features

1. Selective Migration

   • Run migrations on specific components
   • Filter migrations by pattern
   • Target stories by path or query

2. Safe Execution

   • Dry run mode for previewing changes
   • Progress tracking and reporting

3. Publication Control

   • Flexible publishing options
   • Control over which stories get published
   • Support for different publication scenarios

4. Content Filtering

   • Filter by component type
   • Filter by story path
   • Filter by content attributes

Migration File Structure

Migration files should follow this structure:

// hero.amount.js
export default function (block) {
  // Transform block content
  block.amount = Number(block.amount) + 1;
  return block;
}

Testing Strategy

The command includes comprehensive test coverage:

1. Unit Tests
   • Migration file reading
   • Story fetching and filtering
   • Content transformation logic

Testing checklist

Running migrations storyblok migrations run

General

• It should show the command title
• It should throw an error if the user is not logged in You are currently not logged in. Please login first to get your user info.

Required Arguments

[componentName] (optional)

• It should run migrations for all components if no component name is provided
• It should run only migrations that match the component name pattern if provided
• It should match migrations that start with the component name and are followed by either the end of the filename or a dot

-s, --space=TARGET_SPACE_ID

• It should read migration files from .storyblok/migrations/<TARGET_SPACE_ID>/
• It should fetch stories from the target space
• It should fetch full content for each story
• It should apply migrations to the stories
• It should update the modified stories in Storyblok

Error handling

• It should throw an error if the space is not provided: Please provide the space as argument --space YOUR_SPACE_ID.
• It should throw an error if no migration files are found
• It should throw an error if no stories are found

Options

--filter, --fi=<pattern>

• It should apply glob filter to migration files before running them
• It should support patterns like *.amount.js to run specific migrations
• It should show a warning if no migrations match the filter

--dry-run, -d

• It should preview changes without applying them to Storyblok
• It should show what changes would be made
• It should not call updateStory API

--query, -q=<query>

• It should filter stories by content attributes using Storyblok filter query syntax
• Example: --query="[highlighted][in]=true"

--starts-with=<path>

• It should filter stories by path
• Example: --starts-with="/en/blog/"

--publish=<mode>

Supports different publication modes:

• all: Should publish all stories after migration
• published: Should only publish stories that were already published
• published-with-changes: Should only publish stories that have unpublished changes after migration
• No value: Should not publish any stories

Migration Results

• It should show a summary of successful migrations
• It should show a summary of failed migrations
• It should show a summary of skipped migrations
• It should show update progress for each story
• It should show final success/failure counts

[notion-workspace]

run-migration

[edodusi]

@alvarosabu what do you think if we add an extra-confirmation after the run command? I imagine something like:

$ pnpm dev mig run simple_component --space 325977

 Storyblok CLI
 
✔ Found 1 migration files.
✔ Fetched 1 story with related content (filtered by component "simple_component").

Migration "simple-component.js" will be run. This will potentially alter the content of 1 story in your space. Are you sure you want to proceed?
> Yes/No

 Success
✔ Successfully applied 1 migrations to 1 stories
✔ No failures reported

✔ Found 1 stories to update.
✔ Updated story Home - Completed in 182.05ms

 Success
✔ Successfully updated 1 stories in Storyblok.

Stopping at the first question. This is because this command changes content and to me it should require an extra-step, but I don't know if I'm too conservative. What do you think?

[edodusi]

@alvarosabu every other tests passed 👍

[alvarosabu]

@alvarosabu what do you think if we add an extra-confirmation after the run command? I imagine something like:

$ pnpm dev mig run simple_component --space 325977

 Storyblok CLI
 
✔ Found 1 migration files.
✔ Fetched 1 story with related content (filtered by component "simple_component").

Migration "simple-component.js" will be run. This will potentially alter the content of 1 story in your space. Are you sure you want to proceed?
> Yes/No

 Success
✔ Successfully applied 1 migrations to 1 stories
✔ No failures reported

✔ Found 1 stories to update.
✔ Updated story Home - Completed in 182.05ms

 Success
✔ Successfully updated 1 stories in Storyblok.

Stopping at the first question. This is because this command changes content and to me it should require an extra-step, but I don't know if I'm too conservative. What do you think?

That is a good point, mm, considering the client's feedback they actually use the cli migration command as part of their CIs and scripts, so adding a prompt would interfere with that being autonomous. There is also a plan to add interactive or wizard mode in the future. I would say it's ok because the content migration is done by default as a save functionality on the Product, so they could always rollback there or rollback using the migration rollback functionality if something went south