From be466958cf8086fa6134d498cbd38d5fa4a8b6bc Mon Sep 17 00:00:00 2001 From: alvarosabu Date: Mon, 5 May 2025 12:18:45 +0200 Subject: [PATCH] chore: remove outdated README files for components and migrations - Deleted README.md files for components push, pull, and migrations generate/rollback commands as they are no longer relevant to the current project structure. - This cleanup helps maintain a more organized and up-to-date documentation set. --- src/commands/components/README.md | 36 -- src/commands/components/pull/README.md | 221 ------------- src/commands/components/push/README.md | 364 --------------------- src/commands/migrations/generate/README.md | 162 --------- src/commands/migrations/rollback/README.md | 100 ------ 5 files changed, 883 deletions(-) delete mode 100644 src/commands/components/README.md delete mode 100644 src/commands/components/pull/README.md delete mode 100644 src/commands/components/push/README.md delete mode 100644 src/commands/migrations/generate/README.md delete mode 100644 src/commands/migrations/rollback/README.md diff --git a/src/commands/components/README.md b/src/commands/components/README.md deleted file mode 100644 index 7ee5cc7..0000000 --- a/src/commands/components/README.md +++ /dev/null @@ -1,36 +0,0 @@ -# Testing checklist - -## Pushing components `storyblok components push` - -## General - -- [ ] It should show the command title -- [ ] It should trow an error if the user is not logged in `You are currently not logged in. Please login first to get your user info.` -- -### `-s=TARGET_SPACE_ID` - -- [ ] It should read the components files and related resources from **consolidated files**[^1] `.storyblok/components//` - - [ ] It should upsert tags if consolidated files are found `.storyblok/components//tags.json` - - [ ] It should upsert presets if consolidated files are found `.storyblok/components//presets.json` - - [ ] It should upsert groups if consolidated files are found `.storyblok/components//groups.json` - - [ ] It should upsert deep nested groups if consolidated files are found `.storyblok/components//groups.json` - - [ ] It should upsert the components to the target space `.storyblok/components//components.json` - - [ ] It should resolve component whitelists (folders, components, tags) - -#### Error handling -- [ ] It should throw and error if the space is not provided: `Please provide the target space as argument --space YOUR_SPACE_ID. ` - -### `-f=SOURCE_SPACE_ID` - -- [ ] It should use the target space as source if no source space is provided -- [ ] It should read the components files from `.storyblok/components//` -- [ ] It should upsert the components to the target space from the source space - -#### Error handling - -- [ ] It should throw an error if the source space does not exist: `The space folder 'SOURCE_SPACE_ID' doesn't exist yet. Please run 'storyblok components pull -s=SOURCE_SPACE_ID' first to fetch the components.` -- [ ] It should throw a warning if the source space does not have any components (ex components.json is empty or doesn't exist): `No components found that meet the filter criteria. Please make sure you have pulled the components first and that the filter is correct.` - -### `--separate-files` - -[^1] Consolidated files are the default way to store components. They are a single file for each resource (components.json, groups.json, presets.json, tags.json). diff --git a/src/commands/components/pull/README.md b/src/commands/components/pull/README.md deleted file mode 100644 index 8335199..0000000 --- a/src/commands/components/pull/README.md +++ /dev/null @@ -1,221 +0,0 @@ -# Components Pull Command - -The `storyblok components pull` command allows you to download your space's components schema, groups, presets, and internal tags as JSON files. This is useful for version control, backup purposes, or migrating components between spaces. - -## Basic Usage - -```bash -# Pull all components from a space -storyblok components pull --space 295017 - -# Pull a specific component -storyblok components pull my-component --space 295017 -``` - -## Command Options - -| Option | Alias | Description | -|--------|-------|-------------| -| `--space ` | `-s` | (Required) The ID of the space to pull components from | -| `--filename ` | `-f` | Custom name for the consolidated file (default: "components") | -| `--separate-files` | `--sf` | Create individual files for each component | -| `--suffix ` | `--su` | Add a suffix to the file name (e.g., components.{suffix}.json) | -| `--path ` | `-p` | Custom path to store the files (default: ".storyblok/components/{spaceId}") | -| `--verbose` | `-v` | Show detailed logs and error messages | - -## Output Structure - -### Consolidated Files (Default) - -When pulling without the `--separate-files` flag, the command will create a folder `.storyblok/components/{spaceId}` with the following files: - -```markdown -.storyblok/ -└── components/ - └── 295017/ - ├── components.json # All components schemas - ├── groups.json # Component groups - ├── presets.json # Component presets - └── tags.json # Internal tags -``` - -### Separate Files -When using the `--separate-files` flag, each component will be saved in its own file: - -```markdown -.storyblok/ -└── components/ - └── 295017/ - ├── groups.json - ├── tags.json - ├── hero.json - ├── hero.presets.json # Presets used by the hero component - ├── page.json - └── teaser.json -``` - -## Examples - -### Pull all components with default settings - -```bash -storyblok components pull --space 295017 -``` - -Expected output: - -```markdown -.storyblok/ -└── components/ - └── 295017/ - ├── components.json # All components schemas - ├── groups.json # Component groups - ├── presets.json # Component presets - └── tags.json # Internal tags -``` - -### Pull all components into separate files - -```bash -storyblok components pull --space 295017 --separate-files -``` - -Expected output: - -```markdown -.storyblok/ -└── components/ - └── 295017/ - ├── component-groups.json - ├── component-presets.json - ├── component-tags.json - ├── hero.json - ├── page.json - └── teaser.json # One file per component -``` - -### Pull a specific component - -```bash -storyblok components pull hero --space 295017 -``` - -Expected output: - -``` -.storyblok/ -└── components/ - └── 295017/ - ├── hero.json # Only contains the hero component - ├── hero.presets.json # Presets used by the hero component - ├── groups.json # All groups, even if not used by the hero component - └── tags.json # All tags, even if not used by the hero component -``` - -### Pull a specific component with separate files - -```bash -storyblok components pull hero --space 295017 --separate-files -``` - -Expected output: - -```markdown -.storyblok/ -└── components/ - └── 295017/ - ├── hero.json # Only contains the hero component - ├── hero.presets.json # Presets used by the hero component - ├── groups.json # All groups, even if not used by the hero component - └── tags.json # All tags, even if not used by the hero component -``` - -### Pull with custom filename and suffix - -```bash -storyblok components pull --space 295017 --filename my-components --suffix prod -``` - -Expected output: - -```markdown -.storyblok/ -└── components/ - └── 295017/ - ├── my-components.prod.json # All components - ├── groups.json - ├── presets.json - └── tags.json -``` - -### Pull with custom filename and suffix with separate files - -```bash -storyblok components pull --space 295017 --filename my-components --suffix prod --separate-files -``` - -Expected output: - -It will throw an warning: `The --filename option is ignored when using --separate-files` but it will create the files with the suffix. - -```markdown -.storyblok/ -└── components/ - └── 295017/ - ├── hero.prod.json - ├── hero.presets.prod.json - ├── groups.json - └── tags.json -``` - -### Pull to a custom path - -```bash -storyblok components pull --space 295017 --path ./backup -``` - -Expected output: - -```markdown -backup/ -└── components/ - └── 295017/ - ├── components.json - ├── groups.json - ├── presets.json - └── tags.json -``` - -The `components/{spaceId}` folder structure is always maintained regardless of the custom path provided. This ensures consistency across different path configurations. - -## Manual Testing Checklist - -1. Basic Pull Operations - - [ ] Pull all components from a space (consolidated files) - - [ ] Pull a single component by name - - [ ] Verify all related files are created (components.json, groups.json, presets.json, tags.json) - - [ ] Check if file contents are valid JSON - -2. Separate Files Mode - - [ ] Pull all components with --separate-files flag - - [ ] Verify individual component files are created with the correct naming pattern (component-name.json) - - [ ] Check if component relationships are maintained - - [ ] Verify support files (groups, presets, tags) are created - -3. Custom Naming and Paths - - [ ] Test custom filename with --filename flag - - [ ] Test custom suffix with --suffix flag - - [ ] Test custom path with --path flag - - [ ] Verify file naming patterns are correct - -4. Error Handling - - [ ] Test pull without space ID - - [ ] Test pull with invalid space ID - - [ ] Test pull with non-existent component name - - [ ] Verify error messages are clear and helpful - -5. Special Cases - - [ ] Pull components with nested groups - - [ ] Pull components with multiple presets - - [ ] Pull components with internal tags - - [ ] Test verbose mode with --verbose flag diff --git a/src/commands/components/push/README.md b/src/commands/components/push/README.md deleted file mode 100644 index 91578da..0000000 --- a/src/commands/components/push/README.md +++ /dev/null @@ -1,364 +0,0 @@ -# Components Push Command - -The `storyblok components push` command allows you to push component schemas, groups, presets, and internal tags to a target Storyblok space. This is particularly useful for migrating components between spaces or deploying component changes across environments. - -## Prerequisites - -Before pushing components, ensure you have the necessary files in your `.storyblok/components/{spaceId}` directory. These files can be obtained using the `storyblok components pull` command. The file structure should match how you intend to push: - -- For consolidated files: You need the main JSON files (components.json, groups.json, presets.json, tags.json) -- For separate files: You need individual component files plus the support files (groups.json, tags.json) - -## Basic Usage - -```bash -# Push all components to a space -storyblok components push --space 295017 - -# Push a specific component -storyblok components push hero --space 295017 -``` - -## Architecture & Flow - -The push command is organized in three main layers with a specific processing flow to ensure dependencies and references are handled correctly. - -### Command Structure - -```typescript -// 1. Command Layer (index.ts) -componentsCommand - .command('push [componentName]') - // ... options - -// 2. Operations Layer (operations.ts) - - handleWhitelists() - - handleTags() - - handleComponentGroups() - - handleComponents() - -// 3. Actions Layer (actions.ts) - - pushComponent() - - updateComponent() - - upsertComponent() - - pushComponentGroup(); -// ... etc -``` - -### Processing Flow Examples - -#### 1. Simple Component Push -```bash -storyblok components push hero --space 295017 -``` - -Flow: -1. **Read Phase** - ```typescript - // 1. Reads files from .storyblok/components/295017/ - let spaceData = await readComponentsFiles({ - from: '295017', - path: undefined, - separateFiles: false - }); - - // 2. Filters to only include 'hero' component and its dependencies - spaceData = filterSpaceDataByComponent(spaceData, 'hero'); - ``` - -2. **Dependencies Phase** - ```typescript - // 3. Process whitelist dependencies first - const whitelistResults = await handleWhitelists(space, password, region, spaceData); - - // 4. Process remaining tags - const tagsResults = await handleTags(/* ... */); - - // 5. Process remaining groups - const groupsResults = await handleComponentGroups(/* ... */); - ``` - -3. **Component Phase** - ```typescript - // 6. Finally process the hero component - const componentsResults = await handleComponents({ - space, - spaceData, - groupsUuidMap, // Contains mappings of old->new UUIDs - tagsIdMaps // Contains mappings of old->new IDs - }); - ``` - -#### 2. Component with Folders -```bash -storyblok components push component-inside-deep-folder --space 295018 --from 295017 -``` - -Flow: -1. **Group Hierarchy** - ```typescript - // 1. Find all parent groups (Folder B -> Folder C) - function getGroupHierarchy(group: SpaceComponentGroup, allGroups: SpaceComponentGroup[]) { - const hierarchy = [group]; - while (currentGroup.parent_uuid) { - // Add parent to hierarchy - } - return hierarchy; - } - - // 2. Process groups in order (parent first) - for (const group of hierarchy) { - const updatedGroup = await upsertComponentGroup(space, group, /* ... */); - groupsUuidMap.set(group.uuid, updatedGroup.uuid); - } - ``` - -2. **Component Update** - ```typescript - // 3. Update component with new group UUID - const componentToUpdate = { ...component }; - if (component.component_group_uuid) { - const newGroupUuid = groupsUuidMap.get(component.component_group_uuid); - componentToUpdate.component_group_uuid = newGroupUuid; - } - ``` - -#### 3. Component with Whitelists -```bash -storyblok components push page --space 295017 -``` - -If page.json has: -```json -{ - "name": "page", - "schema": { - "body": { - "type": "bloks", - "restrict_type": "groups", - "component_group_whitelist": ["group-uuid-1"], - "component_whitelist": ["hero", "teaser"] - } - } -} -``` - -Flow: -1. **Whitelist Processing** - ```typescript - // 1. Collect all whitelist dependencies - const dependencies = collectWhitelistDependencies(component.schema); - // Result: { - // groupUuids: ["group-uuid-1"], - // componentNames: ["hero", "teaser"] - // } - - // 2. Process whitelisted components first - const whitelistedComponents = spaceData.components.filter( - c => dependencies.componentNames.has(c.name) - ); - ``` - -2. **Update References** - ```typescript - // 3. Update schema with new mappings - updateSchemaWhitelists( - schema, - groupsUuidMap, // group-uuid-1 -> new-uuid - tagsIdMap, // tag mappings - componentNameMap // component name mappings if renamed - ); - ``` - -### Key Architecture Points - -1. **Dependency Order** - - Whitelists → Tags → Groups → Components - - This order ensures all references exist before they're needed - -2. **ID/UUID Mapping** - ```typescript - const maps = { - groupsUuidMap: new Map(), // old UUID -> new UUID - tagsIdMap: new Map(), // old ID -> new ID - componentNameMap: new Map() // old name -> new name - }; - ``` - -3. **Two-Pass System** - ```typescript - // First Pass: Create/update basic component - const updatedComponent = await upsertComponent(space, component); - - // Second Pass (only if needed): Update whitelists - if (hasWhitelists(component.schema)) { - await upsertComponent(space, updatedComponent); - } - ``` - -4. **Error Handling** - ```typescript - const results = { - successful: [] as string[], - failed: [] as Array<{ name: string; error: unknown }> - }; - ``` - -This architecture ensures: -- Dependencies are handled correctly -- IDs and UUIDs are properly mapped -- Folder structures are maintained -- Whitelists are processed in the correct order -- Errors are properly tracked and reported - -## Command Options - -| Option | Alias | Description | -|--------|-------|-------------| -| `--space ` | `-s` | (Required) The target space ID to push components to | -| `--from ` | `-f` | Source space ID (if different from target) | -| `--filter ` | `--fi` | Glob pattern to filter components to push | -| `--separate-files` | `--sf` | Read from separate files instead of consolidated files | -| `--path ` | `-p` | Custom path to read the files from (default: ".storyblok/components/{spaceId}") | -| `--verbose` | `-v` | Show detailed logs and error messages | - -## Push Behavior - -When pushing components, the command follows these rules: - -1. **Dependencies First**: The command automatically handles dependencies in the correct order: - - First, it processes whitelists (if any) - - Components - - Tags - - Groups - - Then, it creates/updates tags - - Next, it handles component groups (maintaining hierarchy) - - Finally, it processes the components themselves - -2. **Smart Updates**: When pushing a specific component or using a filter: - - Only the specified component(s) will be created/updated - - Required dependencies (tags, groups) are automatically identified and created - - Existing dependencies are reused rather than duplicated - -3. **File Mode Matching**: - - If you pulled components with `--separate-files`, you should push with `--separate-files` - - If you pulled components in consolidated mode, push without the `--separate-files` flag - -## Examples - -```bash -# Push all components to a target space -storyblok components push --space 295017 - -# Required files: -.storyblok/ -└── components/ - └── 295017/ - ├── components.json # All components schemas - ├── groups.json # Component groups - ├── presets.json # Component presets - └── tags.json # Internal tags - -# Push a specific component -storyblok components push hero --space 295017 - -# Required files (either): -.storyblok/ -└── components/ - └── 295017/ - └── hero.json # If using separate files -# OR -.storyblok/ -└── components/ - └── 295017/ - └── components.json # If using consolidated files (containing hero component) - -# Push components from a different source space -storyblok components push --space 295017 --from 123456 - -# Required files: -.storyblok/ -└── components/ - └── 123456/ # Note: files are read from source space ID - ├── components.json - ├── groups.json - ├── presets.json - └── tags.json - -# Push using a filter pattern -storyblok components push --space 295017 --filter "page*" - -# Required files: -.storyblok/ -└── components/ - └── 295017/ - ├── components.json # Must contain components matching "page*" - ├── groups.json # Groups used by matching components - ├── presets.json # Presets used by matching components - └── tags.json # Tags used by matching components - -# Push from separate files -storyblok components push --space 295017 --separate-files - -# Required files: -.storyblok/ -└── components/ - └── 295017/ - ├── groups.json - ├── presets.json - ├── tags.json - ├── hero.json - ├── hero.presets.json - ├── page.json - └── teaser.json # All component files - -# Push from a custom path -storyblok components push --space 295017 --path ./backup/components - -# Required files: -backup/ -└── components/ - ├── components.json - ├── groups.json - ├── presets.json - └── tags.json -``` - -## Manual Testing Checklist - -1. Basic Push Operations - - [ ] Push all components to a space (consolidated files) - - [ ] Push a single component by name - - [ ] Verify components are created in target space - - [ ] Check if component configurations match source - -2. Dependency Handling - - [ ] Push component with nested groups - - [ ] Push component with tags - - [ ] Verify groups hierarchy is maintained - - [ ] Check if tags are created correctly - -3. Filter and Source Options - - [ ] Push using filter pattern - - [ ] Push from different source space - - [ ] Test filter with nested dependencies - - [ ] Verify filtered components only are pushed - -4. File Mode Testing - - [ ] Push from separate files - - [ ] Push from consolidated files - - [ ] Test file mode mismatches - - [ ] Verify error handling for missing files - -5. Error Cases - - [ ] Push without space ID - - [ ] Push with invalid space ID - - [ ] Push non-existent component - - [ ] Push with invalid file structure - - [ ] Test verbose error output - -6. Special Cases - - [ ] Push components with presets - - [ ] Push components with whitelists - - [ ] Test custom path scenarios - - [ ] Verify component updates vs creation diff --git a/src/commands/migrations/generate/README.md b/src/commands/migrations/generate/README.md deleted file mode 100644 index 73dd40c..0000000 --- a/src/commands/migrations/generate/README.md +++ /dev/null @@ -1,162 +0,0 @@ -# Migrations Generate Command - -The `storyblok migrations generate` command allows you to generate migration files for specific components. This is useful when you need to transform or update field values across your Storyblok content. - -## Basic Usage - -```bash -# Generate a migration for a specific component -storyblok migrations generate my-component --space 295017 - -# Generate a migration with a custom path -storyblok migrations generate my-component --space 295017 --path ./custom-path - -# Generate a migration with a custom suffix -storyblok migrations generate my-component --space 295017 --suffix staging -``` - -## Command Options - -| Option | Alias | Description | -|--------|-------|-------------| -| `--space ` | `-s` | (Required) The ID of the space to generate migrations for | -| `--path ` | `-p` | Custom path to store the migration files (default: ".storyblok/migrations/{spaceId}") | -| `--suffix ` | `--su` | Suffix to add to the file name (e.g. {component-name}..js) | -| `--verbose` | `-v` | Show detailed logs and error messages | - -## Output Structure - -The command will create a migration file in the following structure: - -```markdown -.storyblok/ -└── migrations/ - └── {spaceId}/ - └── {component-name}.js -``` - -If a suffix is provided, the file will be named: -```markdown -.storyblok/ -└── migrations/ - └── {spaceId}/ - └── {component-name}..js -``` - -## Migration File Structure - -Each generated migration file follows this structure: - -```javascript -export default function (block) { - // Example to change a string to boolean - // block.fullname = !!(block.fullname) - - // Example to transfer content from other field - // block.fullname = block.other_field -} -``` - -## Examples - -### Generate a Basic Migration - -```bash -storyblok migrations generate hero --space 295017 -``` - -This will create: - -```markdown -.storyblok/ -└── migrations/ - └── 295017/ - └── hero.js -``` - -### Generate with Custom Path - -```bash -storyblok migrations generate hero --space 295017 --path ./migrations -``` - -This will create: - -```markdown -migrations/ -└── 295017/ - └── hero.js -``` - -### Generate with Custom Suffix - -```bash -storyblok migrations generate hero --space 295017 --suffix staging -``` - -This will create: - -```markdown -.storyblok/ -└── migrations/ - └── 295017/ - └── hero.staging.js -``` - -## Error Cases - -The command will fail with helpful error messages in the following cases: - -- No component name provided -- No space ID provided -- User not logged in -- Component not found in the space -- Invalid space ID - -## Manual Testing Checklist - -1. Basic Generation - - [ ] Generate migration for a component - - [ ] Verify file is created in the correct location - - [ ] Check if generated file has correct structure - - [ ] Verify component name is correctly set - -2. Path Options - - [ ] Test default path generation - - [ ] Test custom path generation - - [ ] Test custom suffix generation - - [ ] Verify directory structure is maintained - -3. Error Handling - - [ ] Test without component name - - [ ] Test without space ID - - [ ] Test with non-existent component - - [ ] Test while not logged in - - [ ] Verify error messages are clear and helpful - -4. Special Cases - - [ ] Test with complex component names - - [ ] Test verbose mode output - - [ ] Test with various suffix values - - [ ] Verify file permissions are correct - -## Best Practices - -1. **Naming Conventions** - - Use clear, descriptive names for your migration files - - Follow a consistent pattern for component names - - Use meaningful suffixes (e.g., 'staging', 'prod', 'v1') - -2. **Migration Logic** - - Keep migrations atomic (one change per migration) - - Always include validation in your migration logic - - Test migrations on a staging space first - -3. **Version Control** - - Commit migration files to version control - - Include clear documentation of what each migration does - - Use suffixes to differentiate between environments - -## Related Commands - -- `storyblok migrations run` - Apply generated migrations to your content diff --git a/src/commands/migrations/rollback/README.md b/src/commands/migrations/rollback/README.md deleted file mode 100644 index 3acea51..0000000 --- a/src/commands/migrations/rollback/README.md +++ /dev/null @@ -1,100 +0,0 @@ -# Testing checklist - -## Rolling back migrations `storyblok migrations rollback` - -## 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 - -#### `[migrationFile]` (required) -- [ ] It should specify which migration to rollback -- [ ] It should find the corresponding rollback file in `.storyblok/migrations//rollbacks/` -- [ ] It should restore stories to their state before the migration was applied - -### `-s, --space=TARGET_SPACE_ID` - -- [ ] It should read rollback files from `.storyblok/migrations//rollbacks/` -- [ ] It should restore stories from the rollback file -- [ ] It should update each story with its original content -- [ ] It should handle multiple stories in a single rollback - -#### 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 the rollback file is not found -- [ ] It should throw an error if the rollback file is invalid or corrupted -- [ ] It should handle story update failures gracefully - -### Options - -#### `--path=` -- [ ] It should use a custom path for finding rollback files instead of the default `.storyblok/` -- [ ] It should maintain the same directory structure under the custom path - -#### `--verbose` -- [ ] It should show detailed progress information -- [ ] It should show more detailed error messages when failures occur - -### Rollback Process - -- [ ] It should read the rollback file containing original story states -- [ ] It should restore each story to its pre-migration state -- [ ] It should show progress for each story being restored -- [ ] It should continue with remaining stories if one fails -- [ ] It should use spinners to indicate progress -- [ ] It should show success/failure messages for each story - -### Examples - -```bash -# Rollback a specific migration -storyblok migrations rollback migration-name.12345678.json --space 12345 - -# Rollback using a custom path -storyblok migrations rollback migration-name.12345678.json --space 12345 --path /custom/path - -# Rollback with verbose output -storyblok migrations rollback migration-name.12345678.json --space 12345 --verbose -``` - -### Notes - -1. Rollback files are automatically created when running migrations -2. Rollback files are stored in `.storyblok/migrations//rollbacks/` -3. Rollback files contain the original state of all modified stories -4. Rollback files are named with the pattern: `..json` -5. The rollback process restores stories to their exact state before the migration -6. Stories are updated one by one to minimize the risk of data loss -7. The process continues even if some stories fail to update -8. Verbose mode provides detailed progress information - -### File Structure - -``` -.storyblok/ -└── migrations/ - └── 12345/ - ├── hero.js - └── article.amount.js - └── rollbacks/ - ├── hero.1647123456789.json - └── article.amount.1647123456790.json -``` - -### Rollback File Format - -```json -{ - "stories": [ - { - "storyId": 123, - "name": "Story Name", - "content": { - // Original story content - } - } - ] -} -```